FORM Objects + METHODS
Updated: Sep 10, 2008

Object methods perform an action and unlike a property, do not explicitly
return a "result value". 

METHODS    Arguments & Comments
~~~~~~~    ~~~~~~~~~~~~~~~~~~~~
AddItems   Adds string(s).  [COMBOBOX FILELISTBOX LISTBOX]

           MyListBox.AddItems MyString[, NextString, etc]

Background Sets FORM color by W32 COLOR handles 1 - 29 (default = 16)

           MyForm.Background = 6

Buddy      Sets "buddy" of UPDOWN control.  MyUpDown.Buddy = Edit1.Handle

           The default UPDOWN buddy is the previously dimensioned object.

Center     Centers FORM on screen.  MyForm.Center

Circle     Draws circle of radius r centered at x, y with specified color.

           MyForm.Circle x, y, r, rgb_color

ClassStyle Sets class style (default = 8)

           MyForm.ClassStyle = MyClassStyle 'DWORD ClassStyle flags

Clear      Clears text or graphics (CANVAS, TRACKBAR)
           [CANVAS COMBOBOX EDIT FILELISTBOX GRID LISTBOX RICHEDIT RICHEDIT2
            TABCONTROL TRACKBAR TREEVIEW]

           MyListBox.Clear: MyRichEdit.Clear

           For CANVAS, .Clear restores it to a transparent state, but is
           not recommended for high frame rate animations.

           For TRACKBAR, .Clear removes tic marks (see .SetTic).

           For LISTVIEW, .Clear removes items.  With GRID, the removed items
           are the rows; use .InsertRow first, then .Cell() in the new row.

Close      Quits program.  For secondary forms, an .OnClose routine can
           make the form invisible instead of application termination.

Column     For GRID, changes column header text

           MyGrid.Column(n) = "Col C"  'n is 0-based column index

CopyRect   Copies source RECT (r1) of a BITMAP object (bmp1) to a destination
           RECT (r2).  MyObject.CopyRect(r2,bmp1,r1)

           If image dimensions defined by RECT r1 <> RECT r2, then the copied
           image should be stretched or compressed to "fit" r2.  How .CopyRect
           copies the bitmap data is determined by source BITMAP bmp1.Mode.

DelItems   Deletes one or more item(s) by index
           [COMBOBOX FILELISTBOX GRID HEADER LISTBOX LISTVIEW TABCONTROL
            TOOLBAR TREEVIEW]

           MyListBox.DelItems 2, 6  'deletes zero-based items 2 and 6

           Note: item "6" is determined after item "2" above is deleted.

           For TREEVIEW, the "index" is the handle of the item to delete.

Destroy    Destroys window object and frees OS system resources.

           MyObject.Destroy

           Note:  After .Destroy, MyObject is no longer functional.

Directory  Loads directory [COMBOBOX FILELISTBOX LISTBOX]

           Arguments are similar to DIR$ (String Functions).

           MyList.Directory(path$, mask)

           mask bits are the sum of desired "DDL" constants:
           READWRITE (&H0), READONLY (&H1), HIDDEN (&H2), SYSTEM (&H4),
           DIRECTORY (&H10), ARCHIVE (&H20), POSTMSGS (&H2000),
           DRIVES (&H4000) and EXCLUSIVE (&H8000)

           MyList.Directory("c:\*.*",&H37) 'loads directories and files

Draw       Draws BITMAP object at x, y position

           MyObject.Draw 10,10,MyBitmap  'draw at MyObject position 10, 10  

           The drawn rectangle of MyBitmap is determined by its properties. 

Edit       Sets edit style COMBOBOX.  MyCombobox.edit = true

           Save "box" data if needed before changing .edit status.
           If .edit = true, the OS reroutes .OnKeyDown and .OnKeyUp events 
           to the EDIT control embedded in the COMBOBOX.

Ellipse    Draws ellipse (or circle) with the specified color.

           MyForm.Ellipse x1, y1, x2, y2, rgb_color

EndPaint   Used after FORM drawing/painting methods begun with .BeginPaint,
           but not in .OnPaint procedures.

           MyObject.EndPaint  'see numeric function .BeginPaint

ExtendedSelect  
           Sets extended select style [LISTBOX FILELISTBOX]

           MyListBox.ExtendedSelect = true  'default false

FillCircle Draws circle of radius r centered at x, y filled with color.

           MyForm.FillCircle x, y, r, rgb_color

FillEllipse 
           Draws ellipse (or circle) filled with the specified color.

           MyForm.FillEllipse x1, y1, x2, y2, rgb_color

FillRect   Draws rectangle (or square) filled with the specified color.

           MyForm.FillRect x1, y1, x2, y2, rgb_color

           All the .Fill... methods draw within the frame specified by
           the point parameters.  E.g., the same point parameters may be
           used to draw a frame (.Rectangle) and then fill it (.FillRect).

Focus      Sets focus to object.  MyObject.Focus

ForeColor  Sets GAUGE foreground (bar) RGB color.  Please see .Color. 

Foreground Sets FORM as foreground window.  MyForm.Foreground

Group      Specifies the first control of a group of controls. The user can
           change the keyboard focus from one control in the group to the
           next by using the direction keys [win32.hlp].
           MyObject.Group = true

HideSelection
           Hides selection.  [RICHEDIT2]

           MyEdit.HideSelection = true  'default false

Hint       Sets short hint text message when mouse moves over object.
 
           MyEdit.Hint = "Your PentHouse password"
           MyListBox.Hint = "Saved to file mywork.log on close"

           The application main FORM must have .ShowHint = true.

InsertCol  Adds column to GRID view.  MyGrid.InsertCol n, string
           where n is 0-based column index and string is label.

           MyGrid.InsertCol 0,"Column A"

           Note: GRID column label can be changed later with .Column
           Default column width = 60.

InsertItem Inserts item at index position.
           [COMBOBOX FILELISTBOX HEADER LISTBOX TABCONTROL TOOLBAR TREEVIEW]

           MyListBox.InsertItem(3,item$)  'inserts item$ at position 3

           Unlike .AddItems, .InsertItem does not elicit resorting of items.

           For TREEVIEW, if index is 0, a new item is added.  If index is
           the handle of another TREEVIEW item, the new item is inserted as
           a child of that item.  RETFUNC after .InsertItem gets handle:

           MyTV.insertitem 0, "Properties"  '0 means add to TV root
           hTVitem = RETFUNC  'get handle of inserted item

InsertRow  Adds row to GRID view.  MyGrid.InsertRow n, string
           where n is 0-based row index and string is label.

           MyGrid.InsertRow 0,"Row 1"

Line       Draws line from x1, y1 to x2, y2 with rgb color.

           MyForm.Line x1, y1, x2, y2, rgb_color

LoadFromDate
           Loads DATETIME object from a DATE object.

           MyDateTime.LoadFromDate MyDate

LoadFromFile 
           Loads file into object.
           [COMBOBOX, FILELISTBOX, LISTBOX, RICHEDIT, RICHEDIT2]

           MyRichEdit.LoadFromFile "myfile.txt"

           Loads .bmp file into IMAGE or BUTTON

           MyImage.LoadFromFile "myfile.bmp"

MaximizeBox 
           FORM displays maximize box in title bar; default = true
           MyForm.MaximizeBox = false  'no maximize box

MinimizeBox 
           FORM displays minimize box in title bar; default = true
           MyForm.MinimizeBox = false  'no minimize box

MultiSelect
           Sets multiple select style [LISTBOX FILELISTBOX]

           MyListBox.MultiSelect = true  'default false

Number     Restrict text to numbers.  [EDIT RICHEDIT RICHEDIT2]

           MyEdit.Number = true  'default false

Paint      Fills region with rgb_border color containing x, y with rgb_fill.

           MyObject.Paint x, y, rgb_fill, rgb_border 

Password   Sets EDIT password mode.  MyEdit.Password = true  'or false

Pixel      Sets pixel x, y with color.  MyForm.Pixel(x, y)=rgb_color

Pset       Sets pixel x, y with color.  MyForm.Pset(x, y)=rgb_color

Range      Sets range -- minimum and maximum values
           [GAUGE SCROLLBAR TRACKBAR UPDOWN]

           Default = 0 for minimum and 100 for maximum

           MyScrollBar.Range = 0, 255  'to use it to set a RGB color value.

ReadOnly   Disables editing by user.  [EDIT RICHEDIT RICHEDIT2]

           MyEdit.ReadOnly = true  'default false

Recreate   Creates previously destroyed object again.  MyObject.Recreate

           For some FORM objects, Windows apparently cannot or will not
           change some .Style/.ExStyle bits on the fly.  If so, immediately
           after your DIM/CREATE, set the desired .Style or .ExStyle, then
           do a .Destroy and .Recreate sequence to create another object
           with the desired features.

Rectangle  Draws rectangle (or square) with the specified color.

           MyForm.Rectangle x1, y1, x2, y2, rgb_color

ReDraw     Enables/disables object redrawing; default = true/enabled

           MyObject.ReDraw = false  'turns off redrawing by the system

  Programs run faster if .ReDraw is off/false during multiple content changes.

ReleaseDC  Releases internal DC handle from .GetDC.  MyObject.ReleaseDC

RePaint    Signals system that object needs repainting.  MyObject.Repaint

           Used to elicit an .OnPaint event for custom drawing of object. 

Replace    Replace item at index with string
           [COMBOBOX FILELISTBOX HEADER LISTBOX TABCONTROL TOOLBAR TREEVIEW]

           MyObj.Replace 3, "three"  '0-based item 3 replaced with "three"

Resizeable Enables/disables FORM object resize.  default = true

           MyForm.Resizeable = false  'prevent user resizing form

SaveToDate Saves DATETIME object to a DATE object.

           MyDateTime.SaveToDate MyDate

SaveToFile Saves file with object data.
           [COMBOBOX, FILELISTBOX, LISTBOX, RICHEDIT, RICHEDIT2]

           MyRichEdit.SaveToFile "myfile.txt"

ScrollCaret Brings cursor postion into view [EDIT RICHEDIT RICHEDIT2]

           MyRichEdit.ScrollCaret

SetTic     Sets a tic mark display for TRACKBAR.

           'Example showing defaults and how to set tic marks
           MyTrackBar.Clear
           FOR i = 0 TO 100 STEP 5: MyTrackBar.SetTic = i: NEXT i 

Show       Displays FORM and its child components.

ShowAbout  Displays Microsoft Windows about box with program icon for FORM.

           MyForm.ShowAbout("My program#Best Ever","Copyright 2005 My Name")

           Argument strings: (1) consists of two strings separated by "#"
           for title and first text line and (2) any string for about text. 

ShowHint   Creates a ToolTip control for all .Hint text assigned to individual
           GUI objects in all forms in the application.  [FORM, SPLASH]

           MyForm.ShowHint = true  'create and/or activate ToolTips
           MyForm.ShowHint = false 'inactivates ToolTips

ShowModal  Displays FORM and its child components.  Program continues when
           the FORM is closed.

Sorted     Sets sorted style [COMBOBOX FILELISTBOX LISTBOX]

           MyListBox.Sorted = true
           Default = 0 for LISTBOX, = 1 for COMBOBOX and FILELISTBOX
           Save "box" data if needed before changing .Sorted status.

TabStop    Object gets keyboard focus when user presses TAB.
           Default usually is true (check .Style for particular objects).

           MyObject.TabStop = true

TabStops   Sets tab stops to make columns of data [LISTBOX, FILELISTBOX]

           MyListBox.TabStops n, array  'n = number of tab stops

           array is long array of tabstops.  Example in hothead.bas.

TextOut    Draws text string at x, y with text and background colors.

           MyForm.TextOut x, y, "HotBasic Artist", text_color, bk_color

Vertical   Sets to vertical orientation [GAUGE SCROLLBAR TABCONTROL TRACKBAR]

           Default = 0, horizontal

           MyGauge.Vertical = true 'now the progress bar goes up!

           For SCROLLBAR and TRACKBAR, .Vertical = true should appear first
           in code else you will have to restate handle-specific properties
           such as .Hint, etc.


+ Penthouse (registered) version

Copyright 2003-2007 James J Keene PhD
Original Publication: Nov 18, 2003
