🐒 B4XTurtle - Reference

Status
Not open for further replies.

Erel

B4X founder
Staff member
Licensed User
Longtime User
This tutorials will explain how B4XTurtle library works and its various features. B4XTurtle is a cross platform library which is distributed as a b4xlib. You need to download it and copy it to the additional libraries folder.

B4XTurtle type is a custom view and it should be added with the visual designer.
It is very important to understand that B4XTurtle is a regular library and it can be used together will all other B4X features. This is also true for the layout.

The Start event is raised after the layout is loaded:
B4X:
Sub Turtle_Start
    Turtle.MoveForward(100)
End Sub

The turtle canvas size is printed in the logs. You can get it at runtime with Turtle.Width and Turtle.Height.
Note that you should not use 'dip' units with B4XTurtle. Scaling is handled internally.

X goes from left to right.
Y goes from the top to the bottom.
(0, 0) is the top left corner.

0 degrees = turtle points to the left. The degrees go clockwise.

B4X:
Turtle.SetAngle(135).MoveForward(50)
Result:
B4A_RNSCfysClK.png


In the default mode, turtle mode, the actions are queued and are processed sequentially.
This provides a nice effect where most operations are animated.
You can control the speed with SetSpeedFactor method or by changing the DegreesPerSecond and DistancePerSecond fields. There is another mode - rabbit mode, where the actions are executed immediately.

The methods are:

MoveForward (Distance)
MoveBackward (Distance)
TurnLeft (Angle)
TurnRight (Angle)
MoveTo (X, Y) - Turns towards the given point and moves to that point.
SetX (X) - Sets the X coordinate.
SetY (Y) - Sets the Y coordinate.
SetAngle (Angle) - Sets the angle.
DrawText (Text) - Draws text.
ClearRect (X, Y, Width, Height) - Clears the drawing from the given rectangle.
Home - Puts the turtle in the center.
ClearScreen - Immediately clears the screen. This task is added to the queue's head.
Pause / Resume - Pauses or resumes the actions.
Stop - Immediately stops the turtle and clears the tasks queue.
IsMoving - Tests whether the actions queue is not empty.
SetPenSize (Size) - Sets the pen thickness.
SetPenColor (Color) - Sets the pen color (XUI.Color_X or value from color picker).
PenUp / PenDown - Lifts or puts back down the pen. When the pen is up the turtle will move without drawing.
SetSpeedFactor (Factor) - Increases or decreases the movement speed. Default value is 1.
SetFontAndAlignment (Font, Alignment) - Sets the font and alignment that will be used when drawing text. Example:
B4X:
Turtle.SetFontAndAlignment(xui.CreateDefaultBoldFont(20), "LEFT")
RabbitMode / TurtleMode - Enables or disables rabbit mode (immediate mode).
SetTurtleVisible (Visible) - Shows or hides the turtle icon.
PushState - Stores the current state. This allows you to make changes to the state and latest restore the previous state with PopState.
PopState - Restores the previously stored state.
Example of using these methods to create a sub that draws a blue square without affecting the previous set color:
B4X:
Sub DrawBlueSquare
    Turtle.PushState
    Turtle.SetPenColor(xui.Color_Blue)
    For i = 1 To 4
        Turtle.MoveForward(50).TurnLeft(90)
    Next
    Turtle.PopState
End Sub
Fill - Starts a fill action from the current point. Note that this action can be slow on mobile devices.
Arc (SweepAngle, Radius) - Draws an arc. The arc center will be in front of the turtle.
RandomColor - Returns a random color.
StartPolygon - Adds the current point to the polygon points and starts tracking the turtle following points.
FillPolygon - Fills the polygon created by the list of points. Clears the list and stops tracking.
GetX / GetY / GetAngle - Returns the current X, Y or angle values. It is important to remember that in the default mode the tasks are queued and these methods return the current value.

B4X:
Sub Turtle_Start
    Log(Turtle.GetX) 'outputs 400 (center)
    Turtle.SetX(200)
    Log(Turtle.GetX) 'still outputs 400
End Sub
This is the main reason that the rabbit mode was added:
B4X:
Sub Turtle_Start
    Turtle.RabbitMode
    Log(Turtle.GetX) 'outputs 400 (center)
    Turtle.SetX(200)
    Log(Turtle.GetX) 'outputs 200
End Sub

Another option is to wait for the Done event:
B4X:
Sub Turtle_Start
    Log(Turtle.GetX) 'outputs 400 (center)
    Turtle.SetX(200)
    Wait For Turtle_Done
    Log(Turtle.GetX) 'outputs 200
End Sub
This event is raised whenever the queue becomes empty. Note that if you are not sure whether the queue is non-empty then it is safer to implement this event with:
B4X:
If Turtle.IsMoving Then
    Wait For Turtle_Done
End If
This is not needed in the previous code.

The third event is the Touch event. It is raised when the user touches the turtle canvas:
B4X:
Sub Turtle_Touch (Args As TurtleTouchArgs)
    If Args.Down Then
        Turtle.MoveTo(Args.X, Args.Y)
    End If
End Sub

Continue here: https://www.b4x.com/android/forum/threads/🐒-b4xturtle-examples-for-teachers-and-parents.116979/
 
Last edited:
Status
Not open for further replies.
Top