KBasic

Provides common functionality for all controls

• Click Control for more information.

A form itself is a control, which is a window with controls.

• Click Form for more information.

This is the parent class of all forms providing common functionallity for all forms. It receives mouse, keyboard and other events from the window system, and paints a representation of itself on the screen.

In your KBasic-application forms are not only masks for inputting and changing data, but they are the graphical interface of your application. In the eyes of the beholder, they are the application! By creating your application using forms, you control the program flow with events, which are raised in the forms.

Central meaning of forms: Each form in a KBasic application has got a form module with event procedures. Those event procedures react on events raised in the form. Additionally, every module can contain other non-event procedures.

A form module is part of every form, when you copy a form, its form module is automatically copied, too. If you delete a form, its form module is deleted as well. KBasic creates a form module automatically. So you need only to write the event procedures and other procedures.

Forms keep your KBasic program together!

The control class contains functionallity for both controls and forms. Some of it makes only sense when working with forms, others when working with non-form controls.

Override the event methods of Control, when you would like to implement your own controls for display data or interact with the user. Normally, you override OnPaint(…) at least.

' opening a form
Dim f As bernd ' assume that bernd is a form class created with the form designer
f = New bernd
f.Open()

' OR

Forms.Open("bernd") ' for this call you must setup mainwindow in projects properties

Since KBasic V1.6 (k) all forms are automatically declared as global variables accessable from everywhere. So if you had a form named 'myForm', you could use it like this

' code somewhere in your module or other form module

myForm.Open ' if myForm is already opened, it is shown and get the focus only
myForm.Caption = "hello"

A control for the form object, provides a push button or even an option button.

The command button, or push button, is perhaps the most commonly used control in any graphical user interface. Push (click) a button to command the computer to perform some action, or to answer a question. Typical buttons are OK, Apply, Cancel, Close, Yes, No and Help.

A command button is rectangular and typically displays a text label describing its action. An underlined character in the label (signified by preceding it with an ampersand in the text) indicates an accelerator key. Command buttons can display a textual label or an icon.

It is possible to add auto-exclusive behaviour for controls with the same group.

• Click CommandButton for more information.

Implemented since KBasic V1.8

A control for the form object, provides a Vista style command link button.

The command button, or push button, is perhaps the most commonly used control in any graphical user interface. Push (click) a button to command the computer to perform some action, or to answer a question. Typical buttons are OK, Apply, Cancel, Close, Yes, No and Help.

It is possible to add auto-exclusive behaviour for controls with the same group.

• Click CommandLinkButton for more information.

Implemented since KBasic V1.79.

A control for the form object, provides a push button in tool style.

The command button, or push button, is perhaps the most commonly used control in any graphical user interface. Push

• Click ToolButton for more information.

Implemented since KBasic V1.77.

A control for the form object, provides a push button with image effects or even an option button with image effects.

It is possible to add checkable behaviour for controls with the same group.

• Click ImageButton for more information.

A control for the form object, provides a text or image display or even an clickable underlined HTML label.

It is used for displaying text or an image. No user interaction functionality is provided. You can display HTML text with it too.

• Click Label for more information.

A control for the form object, provides a checkbox with a text label.

It can be switched on (checked) or off (unchecked). It is possible to add auto-exclusive behaviour for controls with the same group.

• Click CheckBox for more information.

A control for the form object, provides a radio button.

It can be switched on (checked) or off (unchecked). It is possible to add auto-exclusive behaviour for controls with the same group.

• Click RadioButton for more information.

A control for the form object, is an one-line text editor.

It allows the user to enter and edit a single line of plain text with a useful collection of editing functions, including undo and redo, cut and paste, and drag and drop.

• Click TextBox for more information.

A control for the form object, provides a group box frame with a title.

• Click Frame for more information.

A control for the form object, is a combined button and popup list.

A combobox is a selection control which displays the current item and can pop up a list of items. Comboboxes provide a means of showing the user's current choice out of a list of options in a way that takes up the minimum amount of screen space.

• Click ComboBox for more information.

A control for the form object, provides a list of selectable, read-only items.

This is typically a single-column list in which either no item or one item is selected, but it can also be used in many other ways.

If you need a multi-column list, please use the TreeView control as shown in the list view example project of KBasic.

• Click ListBox for more information.

A control for the form object for editing dates.

It allows the user to edit dates by using the keyboard or the arrow keys to increase and decrease date values. Dates appear in accordance with the format set.

• Click DateBox for more information.

A control for the form object for editing times.

It allows the user to edit times by using the keyboard or the arrow keys to increase and decrease time values. Times appear in accordance with the format set.

• Click TimeBox for more information.

A control for the form object for editing dates and times.

It allows the user to edit dates and times by using the keyboard or the arrow keys to increase and decrease date and time values. Dates and times appear in accordance with the format set.

• Click DateTimeBox for more information.

• Click Timer for more information.

Implemented since KBasic V1.7.

• Click Sound for more information.

Formely, named “Movie” before V1.82.

Implemented since KBasic V1.7.

• Click MovieBox for more information.

Formely, named “Tab” before V1.81.

• Click TabView for more information.

Formely, named “Image” before V1.82.

A control for the form object, provides an image representation.

• Click ImageBox for more information.

A control providing information in a tree structure. It might be used as list view as well, because you can create lists with several columns, but the coding is the same.

• Click TreeView for more information.

The Qt documentation in C++ of this class (QTreeWidget) can be read here: http://doc.trolltech.com/4.3/qtreewidget.html

A control providing information in a list structure. It is actually a TreeView.

• Click TreeView to get detailed information.

Example

Your form contains of TreeView1 (control type TreeView).

Sub Form_OnOpen()

  TreeView1.SetHeaderLabel("name", 0)
  TreeView1.SetHeaderLabel("age", 1)
  TreeView1.SetHeaderLabel("city", 2)
  TreeView1.SetHeaderLabel("cat", 3)
  
  Dim id As Integer 
  Dim i As Integer 
  
  TreeView1.SetColumnWidth(0, 200)
  TreeView1.SetColumnWidth(1, 100)
  TreeView1.SetColumnWidth(2, 100)
  TreeView1.SetColumnWidth(3, 100)
  
 Do 
   i = i + 1
   If i > 10 Then Goto r
   id = TreeView1.AppendChild("")
    
   TreeView1.SetCaption(id, 0, "bernd" & i)
   TreeView1.SetCaption(id, 1, "28" & i)
   TreeView1.SetCaption(id, 2, "Frankfurt" & i)
   TreeView1.SetCaption(id, 3, "Balthasar" & i)
   TreeView1.SetIcon(id, 0, "button_ok.png")
  Loop While( True )
  
  r:
  TreeView1.SetColumnWidth(0, 200)
  TreeView1.SetColumnWidth(1, 100)
  TreeView1.SetColumnWidth(2, 100)
  TreeView1.SetColumnWidth(3, 100)

End Sub 

The Qt documentation in C++ of this class (QWidget) can be read here: http://doc.trolltech.com/4.3/qwidget.html

Please read the control class overview Control as well.

You might want to use it to override the event methods of Control, when you would like to implement your own controls for display data or interact with the user. Normally, you override OnPaint(…) at least.

Example

Your form contains of Box0 (control type Box).

Sub Box0_OnPaint(X As Integer, Y As Integer, Width As Integer, Height As Integer)
  Painter.DrawRect(11, 22, 33, 44)
End Sub

Not implemented yet:

Methods:

• Function Pixmap() As Pixmap
• Function Save(FileName As String) As Boolean

A control for the form object, provides a horizontal progress bar.

A progress bar is used to give the user an indication of the progress of an operation and to reassure them that the application is still running. The progress bar uses the concept of steps; you give it the total number of steps and the number of steps completed so far and it will display the percentage of steps that have been completed.

• Click ProgressBar for more information.

Formely, named “Editor ” before V1.82.

• Click RichTextBox for more information.

Formely, named “Web” before V1.82.

• Click WebView for more information.

Formely, named “Browser” before V1.82.

• Click HtmlView for more information.

Implemented since KBasic V1.8

The Qt documentation in C++ of this class (QSizeGrip) can be read here: http://doc.trolltech.com/4.4/qsizegrip.html

Please read the control class overview Control as well.

Formely, named “Svg” before V1.82.

Implemented since KBasic V1.8

A control for the form object, provides an image representation.

• Click SvgBox for more information.

Implemented since KBasic V1.81

A control for the form object, provides a vertical or horizontal slider.

• Click Slider for more information.

Implemented since KBasic V1.82

A control for the form object, provides a vertical or horizontal scroll bar.

• Click ScrollBar for more information.

Implemented since KBasic V1.81

A control for the form object, allows the user to choose a value by clicking the up/down buttons or pressing up/down on the keyboard to increase/decrease the value currently displayed.

• Click SpinBox for more information.

The Qt documentation in C++ of this class can be read here: http://doc.trolltech.com/4.3/qaction.html

Use the following static function of the class MenuBar to get the menubar item of the current menubar.

• Function MenuBarItem(Name As String) As MenuBarItem

Dim i As MenuBarItem = MenuBar.MenuBarItem("File")
i.Enabled = True

Since KBasic V1.6 (k) all menubaritems are automatically declared as global variables accessable from everywhere. So if you would have a menubaritem named 'openfile', you could use it like this openfile.Enabled = False

Properties are

• Name As String
• ControlType As String (ReadOnly)
• Caption As String
• Text As String

Same as Caption. Provided for easy-use.

• Tag As String
• Separator As Boolean
• Enabled As Boolean
• Checked As Boolean
• Icon As String

An icon can be an absolute path to an image file (png, jpg,…) like c:\myfolder\myimage.png or can be an relative path to the current project like myimage.png (which is present in the current project directory). Relative paths are recommended.

Might be a String containing binary data. See the binary project example for using.

• Key As String

Default keys are

• ParentControl As String (ReadOnly/Hidden)
• ParentIndex As Integer (ReadOnly/Hidden)

Events are

• Sub OnEvent()

This event is raised, whenever the user click on the menubar item.

The following features are implemented since KBasic V1.6 (m)

Properties are

• Group As String

Adds exclusively radiobutton-like checked/unchecked behaviour.

The following features are implemented since KBasic V1.6 (n)

Properties are

• Visible As Boolean
• Checkable As Boolean
• Data As String
• MenuBarRole As String

Possible values are NoRole, TextHeuristicRole, ApplicationSpecificRole, AboutQtRole, AboutRole, PreferencesRole, QuitRole

This describes how an menibaritem should be moved into the application menu on Mac OS X.

The following features are implemented since KBasic V1.76

• ActionId As String

The Qt documentation in C++ of this class can be read here: http://doc.trolltech.com/4.3/qaction.html

Use the following static function of the class ToolBar to get the toolbar item of the desired toolbar.

• Function ToolBarItem(Name As String) As ToolBarItem

Since KBasic V1.6 (k) all toolbaritems are automatically declared as global variables accessable from everywhere. So if you would have a toolbaritem named 'openfile', you could use it like this openfile.Enabled = False

Dim i As ToolBarItem = ToolBar.ToolBarItem("File")
i.Enabled = True

Properties are

• Name As String
• ControlType As String (ReadOnly)
• Tag As String
• Separator As Boolean (ReadOnly)
• Enabled As Boolean
• Icon As String

An icon can be an absolute path to an image file (png, jpg,…) like c:\myfolder\myimage.png or can be an relative path to the current project like myimage.png (which is present in the current project directory). Relative paths are recommended.

Might be a String containing binary data. See the binary project example for using.

• ToolTip As String
• StatusTip As String
• WhatsThis As String
• ParentIndex As Integer (ReadOnly/Hidden)

Events are

• Sub OnEvent()

This event is raised, whenever the user click on the toolbar item.

The following features are implemented since KBasic V1.6 (n)

Properties are

• Group As String

Adds exclusively radiobutton-like checked/unchecked behaviour.

• Caption As String
• Text As String

Same as Caption. Provided for easy-use.

• Checkable As Boolean
• Checked As Boolean
• ToolBarRole As String

Possible values are WhatsThis

• ContextMenu As String
• ArrowType As String

This determines if the it displays an arrow instead of a normal icon. Be sure that you do not set the icon to show the arrow.

Possible values are NoArrow, UpArrow, DownArrow, LeftArrow, RightArrow

• PopupMode As String

Possible values are DelayedPopup, MenuButtonPopup, InstantPopup

The following features are implemented since KBasic V1.76

• ActionId As String

The class Report is used to print database tables. It is based on the class Form.

Please read the class overview of Form as well.

Methods are

• Sub OpenPrintDialog()
• Sub OpenPrintPreview()

Example

' printing a report
Dim f As bernd ' assume that bernd is a report created with the report designer
f = New bernd
f.OpenPrintDialog()

' or use f.OpenPrint()

A control used in reports only. Useful for creating sections on report pages. Not accessable from code.

A control used in reports only. Useful for creating sections on report pages. Not accessable from code.

The SerialPort control is based on QextSerialPort, a cross-platform serial port class. The original documentation about serial programming can be read here: http://qextserialport.sourceforge.net/

The polling technique is used to communicate, which means that, read() and write() are acting synchronously.

Whenever POSIX is mentioned, it refers to Linux and Mac.

Checkout the serialport example comming with KBasic.

Please note: The control SerialPort is still in beta, this basically means it might be not without bugs, and I really want to get your feedback on it. If there is anything you like, don't like, or don't understand, please let me know. Yet several people reported that it works as expected.

Methods are

• Function Open() As Boolean

Important. All settings have to be set before calling “Open”. After that PortName, BaudRate and the other settings must not be changed.

• Function IsOpen() As Boolean
• Function IsReadable() As Boolean
• Function IsWritable() As Boolean
• Sub Close()
• Sub Flush()

Flushes all pending I/O to the serial port. This function has no effect if the serial port associated with the class is not currently open.

• Function BytesAvailable() As Integer

The function BytesWritten() returns the number of bytes waiting in the port's receive queue. This function will return 0 if the port is not currently open, or -1 on error. Error information can be retrieved by calling LastError().

• Sub ReadData(ByRef AnyType)

Reads a block of data from the serial port. This function will read at most maxlen bytes from the serial port and place them in the buffer pointed to by data. Return value of the function BytesRead() is the number of bytes actually read, or -1 on error.

Before calling this function ensure that serial port associated with this class is currently open (use IsOpen() function to check if port is open).

AnyType may be Boolean, Byte, Short, Integer, Single or Double.

• Sub WriteData(AnyType)

Writes a block of data to the serial port. This function will write len bytes from the buffer pointed to by data to the serial port. The function BytesWritten() returns the number of bytes actually written, or -1 on error.

Before calling this function ensure that serial port associated with this class is currently open (use IsOpen() function to check if port is open).

AnyType may be Boolean, Byte, Short, Integer, Single or Double.

• Sub ReadLine(ByRef String)

This function will read a line of buffered input from the port, stopping when either maxSize bytes have been read, the port has no more data available, or a newline is encountered. The value returned by the function BytesRead() is the length of the string that was read.

• Sub WriteLine(String)

This function will write a line.

Don't forget to add the line endings to your string Chr(13) & Chr(10)

• Function BytesRead() As Integer
• Function BytesWritten() As Integer

• Sub SetDtr(Boolean)

Sets DTR line to the requested state. This function will have no effect if the port associated with the class is not currently open.

• Sub SetRts(Boolean)

Sets RTS line to the requested state. This function will have no effect if the port associated with the class is not currently open.

• Function AtEnd() As Boolean

This function will return true if the input buffer is empty (or on error), and false otherwise.

• Function IsCTS() As Boolean
• Function IsDSR() As Boolean
• Function IsDCD() As Boolean
• Function IsRI() As Boolean

Each function returns the line status of the individual line. If it is True, the specified line is set high.

• Function LineStatus() As String

Returns the line status as stored by the port function. This function will retrieve the states of the following lines: DCD, CTS, DSR, and RI. The value returned is a comma-separated list with specific bits indicating which lines are high. The return value should be used to examine the states of individual lines, e.g. return value might be CTS, DSR

This function will return an empty String if the port associated with the class is not currently open.

• Function LastError () As String

^Error^Explanation^

* Function LastErrorText () As String

Returns a description to the error raised.

Properties are

• Name As String (ReadOnly)
• ControlType As String (ReadOnly)

• PortName As String

Other values may be possible depending on your target platform.

• BaudRate As String

Sets the baud rate of the serial port. Note that not all rates are applicable on all platforms. The following table shows translations of the various baud rate constants on Windows and POSIX platforms. Speeds marked with an * are speeds that are usable on both Windows and POSIX.

• DataBits As String

5 data bits cannot be used with 2 stop bits. 1.5 stop bits can only be used with 5 data bits. 8 data bits cannot be used with space parity on POSIX systems.

• FlowControl As String

• Parity As String

• StopBits As String

2 stop bits cannot be used with 5 data bits. 1.5 stop bits cannot be used with 6 or more data bits. POSIX does not support 1.5 stop bits.

• TimeOutMillisec As Integer

Sets the read and write timeouts for the port to millisec milliseconds. Setting 0 indicates that timeouts are not used for read nor write operations. Setting -1 indicates that read and write should return immediately.

• PollingInterval As Integer

Calls OnEvent after PollingInterval milli seconds and if only data is available to read.

PollingInterval = 1000 means 1 second

Events are

• Sub OnEvent()

Formely, named “ChildControl” before V1.81.

Currently, you can only use a name of a form for displaying a child form in another form.

The property “Value” contains the name of the child control.

Methods are

• Function Form() As Form

If you use a formview with sql statements, the parent form must not be in TableView mode. The form used in the formview must be set to TableView mode.

Example

  ' change backgroundcolor in blue
  FormView1.Background = "Blue" ' WRONG! a child control is a place holder for a form only

  Dim f As Form =   FormView1.Form() ' RIGHT! Get the form of the child control and use this for changing properties
  f.Background = "Blue" ' change backgroundcolor in blue

  Dim l As Label = f.Control("Label2")
  l.Caption = "Donnerstag" ' change the caption of the label in the sub form

  ' OR other example the name of the child form 
  Dim f As Form =   FormView1.Form()
  f.Background = "Red"
  Print f.Background
  
  Dim t As TextBox 
  t = f.Control("TextBox0")
  Print t.Value 
  

Not implemented yet:

• Sub SetForm(Form)

Implemented since KBasic V1.8

Displaying children forms in another form.

Methods are

• Sub Append(Form)

Properties are

• SelectionMode() As String

Methods are

• Sub SelectAll(YesNo As Boolean = True)
• Sub Select(Index As Integer, YesNo As Boolean = True)
• Function IsSelected(Index As Integer) As Boolean
• Function Length() As Integer
• Sub RemoveAll()
• Sub Remove(Index As Integer)
• Sub Insert(Index As Integer, Form)
• Sub SetForm(Index As Integer, Form)
• Function Form(Index As Integer) As Form
• Sub ScrollTo(Index As Integer)

The Qt documentation in C++ of this class (QFrame) can be read here: http://doc.trolltech.com/4.4/qframe.html

Please read the control class overview Control as well.

Implemented since KBasic V1.75.

Properties are

• Property Flat As Boolean
• Property Flip As Boolean
• Property Orientation As String

Possible values are Vertical, Horizontal

Constanst are

• Property Line.Vertical As String
• Property Line.Horizontal As String

Implemented since KBasic V1.8

The Qt documentation in C++ of this class (QToolBar) can be read here: http://doc.trolltech.com/4.3/qtoolbar.html

Please read the control class overview Control as well.

The property “Value” contains the name of the toolbar to be shown (“myToolBar” is not allowed).

Methods are

• Sub InsertControl(Index As Integer, Control)

• Function ToolBarItem(ToolBarItemName As String) As ToolBarItem

Dim i As ToolBarItem = ToolBarView1.ToolBarItem("File")
i.Enabled = True

• Sub SetEnabled(ToolBarItemName As String, Boolean)
• Sub SetVisible(ToolBarItemName As String, Boolean)

• Sub SetWithTag(Tag As String, PropertyName As String, Boolean)
• Sub SetWithTag(Tag As String, PropertyName As String, Integer)
• Sub SetWithTag(Tag As String, PropertyName As String, String)

• Sub SetWithGroup(Group As String, PropertyName As String, Boolean)
• Sub SetWithGroup(Group As String, PropertyName As String, Integer)
• Sub SetWithGroup(Group As String, PropertyName As String, String)

Events are

• Sub OnEvent(ToolBarItemName As String)

Implemented since KBasic V1.89

The Qt documentation in C++ of this class (QUdpSocket) can be read here: http://doc.trolltech.com/4.3/qudpsocket.html

Please read the control class overview Control as well.

For each IP you would like to communicate, create a new udpsocket control. (For a server you need a UdpSocket control and for a client.)

Properties are

• Property Host As String

Possible values are LocalHost, LocalHostIPv6, Broadcast, Any, AnyIPv6 or any IP address.

• Property Port As String

Methods are

• Function Bind(Host As String, Port As Integer) As Boolean

Used for writing a server. Tell your program, to listen for Host and Port.

• Function Open() As Boolean

Used for writing a client. Tell your program, to write to Host and Port (properties of the control).

• Sub Close()

Used for writing a client.

• Function ReadData() As String
• Function WriteData(String) As Boolean

• Function LastError() As String

Possible values are ConnectionRefusedError, RemoteHostClosedError, HostNotFoundError, SocketAccessError, SocketResourceError, SocketTimeoutError, DatagramTooLargeError, NetworkError, AddressInUseError, SocketAddressNotAvailableError, UnsupportedSocketOperationError, ProxyAuthenticationRequiredError, SslHandshakeFailedError, UnfinishedSocketOperationError, ProxyConnectionRefusedError, ProxyConnectionClosedError, ProxyConnectionTimeoutError, ProxyNotFoundError, ProxyProtocolError, UnknownSocketError,

Use this function when OnError has been raised only.

• Function LastErrorText(String) As String

Use this function when OnError has been raised only.

Events are

• Sub OnEvent()

Called whenever data arrives ready for reading or writing.

• Sub OnOpen()
• Sub OnClose()

Implemented since KBasic V1.89(i):

• Sub OnError()