From f8de91ae41929286b1cf43c72093e5c996b1f949 Mon Sep 17 00:00:00 2001 From: Ian C Date: Sun, 18 Sep 2005 19:19:36 +0000 Subject: Added documentation --- simplegui.mod/doc/commands.html | 109 ++++++++++++++++++++ simplegui.mod/simplegui.bmx | 223 +++++++++++++++++++++++++++++++++++++--- 2 files changed, 316 insertions(+), 16 deletions(-) create mode 100644 simplegui.mod/doc/commands.html (limited to 'simplegui.mod') diff --git a/simplegui.mod/doc/commands.html b/simplegui.mod/doc/commands.html new file mode 100644 index 0000000..c66334a --- /dev/null +++ b/simplegui.mod/doc/commands.html @@ -0,0 +1,109 @@ + + +BlitzMax Module Reference + + + +

Function Reference

+

+

Function GUINotify( s:String ) Displays a notification alert with the supplied string.

+

+

Function GUIYesNo:Int( s:String ) Displays a yes/no alert with the supplied string.

Returns: True if Yes selected, otherwise False.

+

+

Function GUIMenu( title:String, options:String[],x,y ) Displays a pop-up menu.

Returns: The index of the selected option, -1 for none.

title is the menu title, options the options to display and x and y specify its position,.

+

Type Reference

+

+

Type TGUIFont Defines the TBitmapFont to be used by the GUI.

+

Global font:TBitmapFont The font to use.

+

+

+

Type TWidget Abstract The base widget type.

+

Field enabled:Int If true the widget is displayed and can be used.

+

+

Field text:String The text displayed in the widget.

+

+

Field x:Int The X co-ordinate of the widget.

+

+

Field y:Int The Y co-ordinate of the widget.

+

+

Field w:Int The width of the widget.

+

+

Field h:Int The height of the widget.

+

+

Field callback(w:TWidget) Callback to call when clicked.

+

+

Field mouse_over:Int True if the mouse is over this widget, False otherwise.

+

+

Field owner:TGUIHandler The TGUIHandler that owns this widget.

+

+

Method HandleKey( k:Int ) Override this accept keypresses

+

+

Method MouseEnter() Override this for when the mouse enters. Call this parent version to handle mouse_over too.

+

+

Method MouseLeave() Override this for when the mouse leaves. Call this parent version to handle mouse_over too.

+

+

Method HandleClick() Override to handle a mouse button press.

+

+

Method Draw() Must be provided by a widget to draw itself.

+

+

Function DrawBox( x:Int, y:Int, w:Int, h:Int ) Helper to draw a wireframe rectangle.

+

+

Function Draw3DBox( x:Int, y:Int, w:Int, h:Int, invert:Int, size:Int=2 ) Helper to draw a 3D rectangle.

+

+

+

Type TLabel Extends TWidget The label widget (simply displays the supplied string)

+

Function Create:TLabel( gui:TGUIHandler,x:Int, y:Int, text:String ) Create a TLabel widget.

Returns: The created widget.

gui is the TGUIHandler object managing this wiget. x and y are its position and text is the text to display in the label.

+

+

+

Type TText Extends TWidget The text entry widget

+

Function Create:TText( gui:TGUIHandler,x:Int, y:Int, text:String, maxlen:Int, callback(w:TWidget)=Null ) Create a TText widget.

Returns: The created widget.

gui is the TGUIHandler object managing this wiget. x and y are its position and text is the initial text in the widget. +maxlen is the maximum number of characters allowed. callback is called when RETURN is pressed in the text field.

+

+

+

Type TCheckbox Extends TWidget The checkbox widget

+

Field checked:Int True if the box is checked, False otherwise.

+

+

Function Create:TCheckbox( gui:TGUIHandler, x:Int, y:Int, text:String, callback(w:TWidget)=Null ) Create a TCheckox widget.

Returns: The created widget.

gui is the TGUIHandler object managing this wiget. x and y are its position and text is the text to display by the checkbox. +callback is called when the checkbox is toggled.

+

+

+

Type TButton Extends TWidget The button widget

+

Function Create:TButton( gui:TGUIHandler, x:Int, y:Int, w:Int, h:Int, text:String, callback(w:TWidget) ) Create a TButton widget.

Returns: The created widget.

gui is the TGUIHandler object managing this wiget. x, y, w and h are its position and size, and text is the text to display in the button. +callback is called when the button is pressed.

+

+

+

Type TButtonList Extends TWidget A drop down list type widget

+

Field selected:Int The selected item.

+

+

Function Create:TButtonList( gui:TGUIHandler, x:Int, y:Int, options:String[], selected:Int, callback(w:TWidget) ) Create a TButtonList widget.

Returns: The created widget.

gui is the TGUIHandler object managing this wiget. x and y are its position. options are the options for the list and +selected is the currently selected item. callback is called when the selection changes.

+

+

+

Type TGUIHandler Handles the GUI.

+

Method Register( w:TWidget ) Register a widget.

Widgets call this themselves.

+

+

Method Clear() Remove all widgets.

+

+

Method SetFocus( w:TWidget ) Sets the keyboard focus to the supplied widget. Pass null for no focus.

+

+

Method GetFocus:TWidget() Gets the keyboard focus.

Returns: The currently focused TWidget, or null for no focus.

+

+

Method Clicked:TWidget() Gets the last clicked widget.

Returns: The last clicked TWidget. Null is returned if this is called again before another widget is clicked.

+

+

Method EventLoop() Perform the event loop and pass any necessary events.

KeyHit(KEY_MOUSELEFT) and GetChar() are used to consume events for the interface.

+

+

Function Create:TGUIHandler() Create a GUI Handler.

Returns: The GUI Hanbler.

+

+

Module Information

+ + + + + + + + + +

Framework	(Very) Simple GUI
Copyright	Public Domain
Author	Ian Cowburn
Version	$Revision$

+ + diff --git a/simplegui.mod/simplegui.bmx b/simplegui.mod/simplegui.bmx index 712c61f..bcabdb0 100644 --- a/simplegui.mod/simplegui.bmx +++ b/simplegui.mod/simplegui.bmx @@ -1,3 +1,6 @@ +Rem +bbdoc: noddybox.simplegui +EndRem Module noddybox.simplegui ModuleInfo "Framework: (Very) Simple GUI" @@ -12,38 +15,92 @@ Import brl.Max2D Import brl.Basic Import noddybox.bitmapfont +Rem +bbdoc: Defines the @TBitmapFont to be used by the GUI. +EndRem Type TGUIFont + Rem + bbdoc: The font to use. + EndRem Global font:TBitmapFont End Type +Rem +bbdoc: The base widget type. +EndRem Type TWidget Abstract + Rem + bbdoc: If true the widget is displayed and can be used. + EndRem Field enabled:Int + Rem + bbdoc: The text displayed in the widget. + EndRem Field text:String + Rem + bbdoc: The X co-ordinate of the widget. + EndRem Field x:Int + Rem + bbdoc: The Y co-ordinate of the widget. + EndRem Field y:Int + Rem + bbdoc: The width of the widget. + EndRem Field w:Int + Rem + bbdoc: The height of the widget. + EndRem Field h:Int - Field owner:TGUIHandler + Rem + bbdoc: Callback to call when clicked. + EndRem Field callback(w:TWidget) + Rem + bbdoc: True if the mouse is over this widget, False otherwise. + EndRem Field mouse_over:Int - + Rem + bbdoc: The @TGUIHandler that owns this widget. + EndRem + Field owner:TGUIHandler + + Rem + bbdoc: Override this accept keypresses + EndRem Method HandleKey(k:Int) End Method + Rem + bbdoc: Override this for when the mouse enters. Call this parent version to handle @mouse_over too. + EndRem Method MouseEnter() mouse_over=True End Method + Rem + bbdoc: Override this for when the mouse leaves. Call this parent version to handle @mouse_over too. + EndRem Method MouseLeave() mouse_over=False End Method + Rem + bbdoc: Override to handle a mouse button press. + EndRem Method HandleClick() End Method + Rem + bbdoc: Must be provided by a widget to draw itself. + EndRem Method Draw() Abstract + Rem + bbdoc: Helper to draw a wireframe rectangle. + EndRem Function DrawBox(x:Int, y:Int, w:Int, h:Int) DrawLine(x,y,x+w-1,y) DrawLine(x+w-1,y,x+w-1,y+h-1) @@ -51,6 +108,9 @@ Type TWidget Abstract DrawLine(x,y+h-1,x,y) End Function + Rem + bbdoc: Helper to draw a 3D rectangle. + EndRem Function Draw3DBox(x:Int, y:Int, w:Int, h:Int, invert:Int, size:Int=2) Local f:Int @@ -82,7 +142,15 @@ Type TWidget Abstract End Type +Rem +bbdoc: The label widget (simply displays the supplied string) +EndRem Type TLabel Extends TWidget + Rem + bbdoc: Create a TLabel widget. + returns: The created widget. + about: @gui is the @TGUIHandler object managing this wiget. @x and @y are its position and @text is the text to display in the label. + EndRem Function Create:TLabel(gui:TGUIHandler,x:Int, y:Int, text:String) Local o:TLabel=New TLabel o.enabled=True @@ -101,9 +169,18 @@ Type TLabel Extends TWidget End Type +Rem +bbdoc: The text entry widget +EndRem Type TText Extends TWidget Field maxlen:Int + Rem + bbdoc: Create a TText widget. + returns: The created widget. + about: @gui is the @TGUIHandler object managing this wiget. @x and @y are its position and @text is the initial text in the widget. + about: @maxlen is the maximum number of characters allowed. @callback is called when RETURN is pressed in the text field. + EndRem Function Create:TText(gui:TGUIHandler,x:Int, y:Int, text:String, maxlen:Int, callback(w:TWidget)=Null) Local o:TText=New TText o.enabled=True @@ -153,9 +230,22 @@ Type TText Extends TWidget End Method End Type +Rem +bbdoc: The checkbox widget +EndRem Type TCheckbox Extends TWidget + + Rem + bbdoc: True if the box is checked, False otherwise. + EndRem Field checked:Int + Rem + bbdoc: Create a TCheckox widget. + returns: The created widget. + about: @gui is the @TGUIHandler object managing this wiget. @x and @y are its position and @text is the text to display by the checkbox. + about: @callback is called when the checkbox is toggled. + EndRem Function Create:TCheckbox(gui:TGUIHandler, x:Int, y:Int, text:String, callback(w:TWidget)=Null) Local o:TCheckbox=New TCheckbox o.enabled=True @@ -195,11 +285,20 @@ Type TCheckbox Extends TWidget End Method End Type +Rem +bbdoc: The button widget +EndRem Type TButton Extends TWidget Field ox:Int Field oy:Int + Rem + bbdoc: Create a TButton widget. + returns: The created widget. + about: @gui is the @TGUIHandler object managing this wiget. @x, @y, @w and @h are its position and size, and @text is the text to display in the button. + about: @callback is called when the button is pressed. + EndRem Function Create:TButton(gui:TGUIHandler, x:Int, y:Int, w:Int, h:Int, text:String, callback(w:TWidget)) Local o:TButton=New TButton o.enabled=True @@ -233,6 +332,74 @@ Type TButton Extends TWidget End Method End Type +Rem +bbdoc: A drop down list type widget +EndRem +Type TButtonList Extends TWidget + + Field options:String[] + + Rem + bbdoc: The selected item. + EndRem + Field selected:Int + + Rem + bbdoc: Create a TButtonList widget. + returns: The created widget. + about: @gui is the @TGUIHandler object managing this wiget. @x and @y are its position. @options are the options for the list and + about: @selected is the currently selected item. @callback is called when the selection changes. + EndRem + Function Create:TButtonList(gui:TGUIHandler, x:Int, y:Int, options:String[], selected:Int, callback(w:TWidget)) + Local o:TButtonList=New TButtonList + Local maxw:Int=0 + o.enabled=True + o.x=x + o.y=y + o.options=options + o.selected=selected + o.text=options[selected] + + For Local s:String=EachIn options + maxw=Max(maxw,TGUIFont.font.TextWidth(s)) + Next + + o.w=maxw+TGUIFont.font.MaxHeight()+4 + o.h=TGUIFont.font.MaxHeight()+2 + o.callback=callback + gui.Register(o) + Return o + End Function + + Method HandleClick() + Local sel:Int=GUIMenu("Select value",options,x,y) + + If sel<>-1 + selected=sel + text=options[selected] + If callback<>Null + callback(Self) + EndIf + EndIf + End Method + + Method Draw() + If (mouse_over) + SetColor(128,128,128) + Else + SetColor(64,64,64) + EndIf + + DrawRect(x,y,w,h) + Draw3DBox(x+2,y+2,h-4,h-4,False,1) + + TGUIFont.font.Draw(text,x+TGUIFont.font.MaxHeight()+3,y+1) + End Method +End Type + +Rem +bbdoc: Handles the GUI. +EndRem Type TGUIHandler ' These are private @@ -242,8 +409,10 @@ Type TGUIHandler Field m_over:TWidget Field m_clicked:TWidget - ' Creates a new GUI handler - ' + Rem + bbdoc: Create a GUI Handler. + returns: The GUI Hanbler. + EndRem Function Create:TGUIHandler() Local o:TGUIHandler @@ -257,41 +426,51 @@ Type TGUIHandler Return o End Function - ' Register a widget - ' + Rem + bbdoc: Register a widget. + about: Widgets call this themselves. + EndRem Method Register(w:TWidget) m_widgets.AddLast(w) w.owner=Self End Method - ' Clear widgets - ' + Rem + bbdoc: Remove all widgets. + EndRem Method Clear() m_widgets.Clear() End Method - ' Set the keyboard focus (null for none) - ' + Rem + bbdoc: Sets the keyboard focus to the supplied widget. Pass null for no focus. + EndRem Method SetFocus(w:TWidget) m_focus=w End Method - ' Get the keyboard focus (null for none) - ' + Rem + bbdoc: Gets the keyboard focus. + returns: The currently focused TWidget, or null for no focus. + EndRem Method GetFocus:TWidget() Return m_focus End Method - ' Gets the last clicked widget - ' + Rem + bbdoc: Gets the last clicked widget. + returns: The last clicked TWidget. Null is returned if this is called again before another widget is clicked. + EndRem Method Clicked:TWidget() Local last:TWidget=m_clicked m_clicked=Null Return last End Method - ' Perform a loop and any necessary events - ' + Rem + bbdoc: Perform the event loop and pass any necessary events. + about: KeyHit(KEY_MOUSELEFT) and GetChar() are used to consume events for the interface. + EndRem Method EventLoop() Local x:Int=MouseX() Local y:Int=MouseY() @@ -340,6 +519,9 @@ Type TGUIHandler End Type +Rem +bbdoc: Displays a notification alert with the supplied string. +EndRem Function GUINotify(s:String) Local back:TImage=CreateImage(GraphicsWidth(),GraphicsHeight(),1,0) GrabImage(back,0,0) @@ -368,6 +550,10 @@ Function GUINotify(s:String) Wend End Function +Rem +bbdoc: Displays a yes/no alert with the supplied string. +returns: True if Yes selected, otherwise False. +EndRem Function GUIYesNo:Int(s:String) Local back:TImage=CreateImage(GraphicsWidth(),GraphicsHeight(),1,0) GrabImage(back,0,0) @@ -400,6 +586,11 @@ Function GUIYesNo:Int(s:String) End Function +Rem +bbdoc: Displays a pop-up menu. +returns: The index of the selected option, -1 for none. +about: @title is the menu title, @options the options to display and @x and @y specify its position,. +EndRem Function GUIMenu(title:String, options:String[],x,y) Local f:Int Local back:TImage=CreateImage(GraphicsWidth(),GraphicsHeight(),1,0) -- cgit v1.2.3