Working with the Form Controls
in dBASE

There are sample forms included with this document that show the use of some of the controls, as well as various properties, events and methods of those controls. If you are uncertain how a control works, run the forms and experiment, that's how this document and sample forms were created, experimentation.

Before we get into a discussion of the different controls covered in this document, it's opinion time ... This is an opinion of mine that is shared by most, if not all, experienced dBASE developers: Never, ever use a stock dBASE control for anything! Sooner, or later, you will regret having done so. You will run across something that you need to change on all your forms. That will be a monstrous task, unless you heed this advice. Before you create your first form, you should create a set of base custom controls, upon which all others are based (see the Custom Classes HOW TO for details). The same can be said for your forms (see the Custom Forms HOW TO for details). Never use the stock controls. For the sake of simplicity, this document will use stock controls, but you should check out the HOW TO on Custom Classes to learn something about creating your own custom controls.

---

NOTE: With all the emphasis on using custom controls above, one question might be "How do I change my current controls on forms to custom ones?" Assuming you have a custom control file with your own custom controls, you could open the source code of the form in the source editor (right click and select "Open in Source Editor" (or press after a single click on the icon)). At the beginning of the source code for your form (see below) add the appropriate SET PROCEDURE statement:

       class comboboxForm of FORM
       set procedure to mycontrols.cc additive
       with (this)
          [code snipped]
   

Then use the search and replace options (Ctrl+R) to replace all occurances of specific words with then name of your custom controls, for example -- if using formcntl.cc in the dUFLP library (noted periodically throughout this document), you might replace all occurrances of the words "NEW ENTRYFIELD" with "NEW kmCustEntryField". From this point on the form will use any properties, events and/or methods you have defined for that custom entryfield.

---

There are two ways to get controls onto a form while using the form designer. The first is to use the controls that appear in the Component Palette. The second is, once you have a query or datamodule on your form that is set to open at least one table, is to drag the controls that are already datalinked to fields in the tables to the surface of the form.

---

NOTE: The form designer has a built-in assignment of specific field types to specific controls. When you first install dBASE, you will find that, for example, spinboxes are assigned by default to numeric and date fields. This may not be desireable -- and you can change this in the form designer. Go to the menu (when you have a form in the designer) and select File and then select "Associate Component Types". (You can also do this by right clicking on the field palette and selecting "Associate Component Types" from the popup there.) Note that Numeric and Date types have spinboxes associated with them -- if you select Entryfields for these, this will affect new controls you place in your application until you change the settings back. (This is mentioned because I have very few situations where I prefer spinboxes for numeric and/or date fields, and find I would rather use entryfields for these types. From discussions in the newsgroups, I'm not the only one who feels this way ...)

---

Common Properties, Events, and Methods

Properties, events and methods that are specific to a control are covered in the discussion of that control.

Properties
Properties are the attributes of controls and include among others font, identification, size and visual properties. A property setting can be changed programmatically as well as in the form designer. The setting is normally a single value, for example, a character string, number or reference to another object.

• The dataLink property is one of the the most important, as it is used for any datalinked control that you are linking to a field in a table. In dBASE this means that you have placed onto the surface of the form a query (dragging a table from the navigator, for example), a datamodule, or a datamodref. The query or datamodule contains the references to the table(s), and you can datalink a control from the inspector. If you are using the old XDML form of USE MYTABLE you may also datalink controls to the underlying table.

  The dataLink is "live" -- this means that as soon as you run the form, you are working with the table's field(s).

  ---

  There are a lot of tricks working with tables, and you should read the HOW TO document on OODML, to learn the details. The basics are that you really are working with a record "buffer" -- this means you see on the screen an "image" of the record (or row), and if you make changes, it is to the image. If you navigate or save the changes, then they are written back to the table. However, you can also abandon those changes before they are written to the table. All of this is done automatically for you by the rowset object of dBASE.

  One trick I will suggest here, but you can take it or leave it -- set the rowset object's autoEdit property to false. This will disable changes to a rowset unless the user clicks an edit or append button (which you would need to provide on your form). It also will not affect the color of the entryfields -- see discussion on this in the section on using entryfields.

  ---

• The dataSource property is only used for some of the components (combobox, listbox, notebook, tabbox or image). It can be an array (literal or other) for all but the image control. For the combobox or listbox controls, it can be a field, the structure of a table, a list of files, and more -- these will be discussed at least briefly for those components. For an image, this is the source of the image (a field in a table, a file ...).

• The name property is very handy when working with any of these controls. The problem is when you place any control directly on the form from the component palette, it is given the useful name of "classnameN" where "classname" is the name of the class (i.e., Entryfield), and "N" is a number (i.e., 1). So the first entryfield you place onto a form from the component palette would be named: Entryfield1. This is not the most useful name you could have.

  If you drag a field from the Field palette, you will get a more useful name: "ClassnameFieldnameN", where "Fieldname" is the actual name of the field. If you have spaces in it, these will be removed or replaced with underscores, "Classname" and "N" are the same as above, so if you dragged a "First Name" field to the form from the field palette, you might see a name of EntryfieldFirst_Name1.

  It is a good idea to use descriptive names for your controls, because otherwise, particularly on a complex form, it will get very difficult to know which object is which. You could use something like what is used by the field palette, but unless you have multiple first name entryfields on a form, you can probably remove the number.

• The baseClassName property is useful in that sometimes in your code you may want to loop through the controls on a form to modify how the controls are functioning. baseClassName will always return the type of control, even if you are using custom controls that are subclassed from a stock control. For example, if you have a custom entryfield that you name MyCustEntry, the className property of an instance of that entryfield will be "MYCUSTENTRY", but the baseClassName property will always be "ENTRYFIELD". This is new to dB2K.

• The anchor property (not shared by all controls, but ...) determines where to "anchor" a control -- this allows you to set it to a specific part of the form, and if you resize the form (or you allow your users to) it will always be in the same location ...

• The function and picture properties are used to format the value of a control. A function formats the entire value, while a picture gives you character-by-character control. Suppose you need a 20 character field value formatted in all uppercase characters. You could enter 20 "!"'s in the picture property, or simply set the function property to "!" and leave the picture property blank. Using these two properties together, you can include literal characters in the displayed value that are not part of the actual field value. For example, you can store a phone number in a 10 character field as "8008675309", set the function property to "R" and the picture property to "(999) 999-9999", and the displayed value will be "(800) 867-5309".

• The speedTip property is used to display a cue to the user of what an object is there for. Not all controls have them, but most form controls do. Most form controls have them as of dBASE Plus vers. 2.0.

• The transparent property is for those controls with text -- if this is set to 'true', the background of the form will show and you only have to define the foreground color of the text. The background will default to that of the form and, if the form has a background image, that will show through as well. In dBASE Plus, version 2.10 and later, some controls that did not have a transparent property have been modified to have one. Specifics will be discussed about these when we get to the individual controls, as the behavior may not be what you expect to see.

• The value property returns the current value contained in the control. If you are datalinked to a field in a table, this will be the value in that field (unless the field value is "morphed").

  ---

  "Morphing" a field's value is basically storing one value in the field and displaying a different value in the control that is being used on the form. Morphing can be used in lookup tables, where you store a key or code value in the main table, and perform a lookup in another table -- what the user sees is a completely different value from what is stored in the table. dBL has a method of handling this automatically -- this is discussed with the Combobox control, and can be examined in more detail in the online help under "lookupSQL".

  ---

• The visible property enables you to make a control visible, by setting it to true (the default value), or invisible, by setting it to false.

• The printable property is also what it sounds like. If you use the form's print() method you can print the form layout -- if you set a control's printable property to false, it will not print when you do this.

• The border and borderStyle properties are used to give a specific look to the outline of your controls. Most have a default borderStyle set. You should experiment with these styles to find the one(s) you prefer for your controls ... (see the form RECTANGL.WFM that comes as a sample with this document for how these look ...)

• The dragEffect property is used to specify if a control is draggable, and how it is dragged. The default value is zero (None), but can be 1 (Copy) or 2 (Move). Copy means that if the user drags the control, when the drop it, a copy of the control will be made. Move means that the original control is moved. For more details, see online help, and the Knowledgebase - there should be an article there by Tim Converse on working with Drag an Drop. This is new to dB2K. Most controls in dBASE have this property.

Events
Events are something that controls respond to, a mouse click, a control getting focus, a change in the control's value, etc. Events are always "firing" provided the event is occurring, however, in order to have something happen, you have to "hook" code to the event. (Windows itself is really just a big "event" handler -- it does not do anything until some event is fired ...)

Events whose name begin with ON, such as onOpen, occur after the action to which they refer. Thus, the onOpen event occurs after the form is opened. Events that begin with CAN, such as canClose, must return a logical value that will determine whether the indicated action may proceed. So, a form's canClose event must return true before the form may close. Returning a value of false will prevent the form from closing. Failure to return a Boolean value may yield unpredictable results.

• The key event is called for each keystroke entered by the user (this event is only available for some controls). It has it's uses, but there are some interesting things to note: the keystroke that you are "currently" looking at may not be what you expect. For an example of the use of the key event check out SEEKER.CC in the CUSTOM directory of Visual dBASE 7 (in other versions of dBASE this will be in different locations -- in dBASE PLUS, Seeker is contained in the dBLClasses folder, and under that, in FormControls -- i.e., Plus\dBLClasses\FormControls). You may also want to look at the PASSWORD.CC in the dUFLP library for an interesting method of using the key event to display a different character than the one typed.

• The onChange event fires when the contents of the control change (user changes something or programmatic changes ...). If this is used with radioButtons and you share the code (i.e., each radioButton calls the same event handler), the event handler will be executed twice -- once for the radioButton that was clicked and once for the radioButton that had it's value changed by clicking on another. (See online help for more details.)

• The onGotFocus event fires when a control gains focus -- either by the user tabbing to to the control, clicking on it with the mouse, or a programmatic call to the setFocus() method. This can be used to change the color of the control if the control does not have a colorHighlight property (some don't), and it can be used to execute code you need to have executed only when this control gets focus.

• The onLostFocus event fires when the focus moves to another control on the form. This can be used to do specific validation, to re-set the color for controls that do not have a colorHighlight property, and more.

• The onOpen event fires after the form's onOpen event. This can be used to set default values, to define dataSources for those controls (combobox, listbox ...) that use them, and more.

• The valid event can be used to do field-level validation. Note that this one must return a logical value (true or false), no matter what you do in the code ... if the returned value is "false" the user cannot leave the control until the returned value is "true". (There is more detail in the onLine help for this.) If you use the valid event, you may want to also look at these properties: validRequired and validErrorMsg.

• The when event can be used to disallow access to the control (must return a true or false value). One use of this that is fairly common is that a lot of developers do not like the default Windows behavior used when setting a control's enabled property to false -- the color of the text goes gray -- by not using enabled, and instead, using the when event set to return a false value, the user cannot access the control but the color does not change. ( {; return false} is all that is necessary in this event handler to do this.)

• The onDesignOpen event is used ONLY in the designer. This fires each time the form is opened in the designer, so be careful using it. One thing that this can be very handy for is to assign some "dummy" data or datasource to a control -- but only do this if your onOpen event re-sets this (or it gets set in the form's open/readmodal or onOpen events), as the form designer will stream out to the form's constructor code whatever your datasource is at the time.

• The onOpen event fires both when the form is opened in the designer and when the form is run. NOTE: this event fires AFTER the form itself opens, so be careful what you do here -- you may cause some interesting results in the appearance of your form ...

• The onDragBegin event fires when a user holds the mouse down on a control whose dragEffect property is set to either 1 or 2, and then moves the mouse. For more information, see online help. This is new to dB2K.

Note that there are a set of Mouse events not discussed here (onLeftDblClick, onLeftMouseDown, onLeftMouseUp, etc.). These are pretty obvious when they fire if you look at the names of the events. The onLeftMouseUp (same for onMiddleMouseUp and onRightMouseUp) has the interesting effect that it often gets called twice on a double-click ... if you attempt to use both, you may be shooting yourself in the foot ...

Methods
Methods are code that performs an action. Controls have a number of built in methods which are called through the control, i.e., form.entryfield1.copy(). Code which responds to a control's event is also a method, but not necessarily a method of the control (usually a method of the form).

One thing you should remember is that if you use the built-in methods as a programming hook to insert your own code (this is called over-riding the method), you will nearly always want to call the original built-in method before, during, or after your code. (This would be achieved by entering: SUPER::methodname() into the code ...)

• The setFocus() method is very handy to force a specific control to have focus.

There are more methods than setFocus(), but most of them are either specific to the control, or are pretty straightforward. Some of these are clipboard specific (copy, cut, paste, undo). Some deal with moving the control (move()). You can also explicitly release a control from memory using the release() method. It didn't seem like it was necessary to really spend a lot of time on these.

Data Entry Related Controls

• Entryfield
  The Entryfield control is the most basic of the data entry controls. Nearly all forms that deal with data entry use entryfields for a lot of the data.

  There is not a lot that needs to be said here that isn't covered in the "shared properties ..." section of this document.

  • The key event is used when a user presses a key to evaluate what the keystroke is, and act on it. (This appears in the Combobox and Editor controls as well.)

  ---

  SEEKER: One interesting entryfield that ships with dBASE, and appears in the component palette on the Custom page (unless you have closed all procedures, and such) is a Seeker control.

  This control does not get datalinked to any fields in a table. Its purpose is to perform what is called an "incremental search" -- this is a search that is performed based on what is entered into the entryfield. To use a seeker control see the document in the Knowledgebase concerning "Working With the Custom Classes that Ship WITH dBASE".

  A really great use of the seeker control is to combine it with a "read-only" grid (one with the allowEditing and allowAddRows properties turned off, and the rowSelect property turned on) -- this will show the current row as you use the seeker ...

  See sample form: SEEKER.WFM for an example of this. Note that seeker.wfm creates a dummy table and randomly populates it.

  ---

  Non-Datalinked Entryfields
  There are times that you may need to use an entryfield that is not datalinked to a field in a table. BUT, you may want to obtain data from a user (an example might be to get a starting date for a report, or something of that nature).

  The problem is that entryfields default to the type "Character", with a max length of 25 characters. This means entering a number or a date will not automatically use the standard error checking built in to dBASE and the value you get when you check the entryfield's value property may not be what you were expecting. For example, consider the following code:

         local f
         f = new valuesForm()
         f.open()
         return
  
         class valuesForm of FORM
            with (this)
               scaleFontBold = false
               height = 7
               left = 10
               top = 1
               width = 18
            endwith
  
            this.entryfield1 = new entryfield(this)
            with (this.entryfield1)
               height = 1
               left = 5
               top = 1
               width = 8
            endwith 
  
            this.entryfield2 = new entryfield(this)
            with (this.entryfield2)
               onChange = {;form.entryfield3.value=form.entryfield1.value+this.value}
               height = 1
               left = 5
               top = 2.5
               width = 8
            endwith
  
            this.entryfield3 = new entryfield(this)
            with (this.entryfield3)
               height = 1
               left = 5
               top = 4.5
               width = 8
            endwith
         endclass     
      

  If you copy and paste this code into a dBL program and run it, you will see a form with three entryfields. Enter a numeric value in the first entryfield, tab to the second entryfield, enter another numeric value and press the tab key. The bottom entryfield will contain the results of adding the other two values. What you expected? Probably not. The results would be the same if you tried entering dates. The strings you enter are concatenated instead of adding the numeric values.

  The solution is to use the onOpen event of the entryfield (or a spinbox for that matter), and you can set a value that will force the entryfield to work as a date or numeric type. For dates, you could set a blank date with {} (two curly braces), or you could set a value to the current date using the date() function. For a numeric value, if you do not have a default starting value, simply using zero will work:

         function entryfield1_onOpen
              form.entryfield1.value = {}
              // or:
              // form.entryfield1.value = date() 
              // or {} for empty date
              // or:
              // form.entryfield1.value = 0 // numeric
     

  ---

  dBASE Plus 2.2 and later has changed the way that numeric values are handled. The following is a brief discussion. Note that this apply the same way for Entryfields, Spinboxes, and Grid cells.
  • Numeric values now start entering data from the left of the decimal point, much like calculators and a variety of software. If you type the decimal, the cursor jumps to the right of the decimal point, and data entry goes to the right.

  • Numeric values are left justified in the entryfield (or spinbox ...). In older versions of the software numeric values were right justified in the entryfield/spinbox/etc.

  • Zero values will appear as '.00' when editing. Null values will show an empty entryfield, although if a decimal point is defined, that will appear. (i.e., if your entryfield is datalinked to a numeric field with decimal values ...) What is meant by "when editing" is when the user is in either append or edit mode, and the entryfield has focus. When the entryfield does not have focus, zero values should appear as '0.00' (unless a picture or function is defined, in which case the picture and/or function will take effect as soon as the cursor exits the entryfield).

  • It is a good idea to set the picture property (ex. "9999.99", if your numeric field is defined as width of 7 with two decimal places, for example). If you use a picture without any decimals (values to right of the decimal point), i.e., "999", and the value is zero, you will see a zero.

  • When you are adding or entering numeric data that has been formatted with the picture and/or function properties these will disappear when the entryfield has focus (while modifying the data), and once the entryfield loses focus the data will be formatted appropriately.

  • The entryfield's selectAll property will act like always -- if the property is true (the default state) then tabbing to an entryfield will highlight everything and if the user types, whatever is contained in the entryfield will be over-written, and entry will start at the decimal point (numbers will move left) as described above.
    

    If the selectAll property is false, tabbing to the entryfield will not highlight what is in the entryfield. The cursor will start at the left of the entryfield, and the user may need to delete numbers in the entryfield.

  • If the user clicks on the entryfield with the mouse, the cursor will appear where they clicked.

  ---

• Spinbox
  The spinbox control is really just an entryfield with a couple of pushbuttons added to the right. It is used for numeric or date values, to increment or decrement the values by using the buttons (which show up/down arrowheads).

  The spinbox has all the characteristics of the entryfield, and the following as well:

  • The rangeMax, rangeMin , rangeRequired properties are used to set a top/lower value and to enforce that value -- i.e., if the rangeRequired property is set to "true" the user cannot move past the rangeMin or rangeMax values or enter a value outside that range.

  • In addition, there is the spinOnly property -- this can be used to enforce the use of the buttons, and ONLY the buttons by the user -- they cannot enter a value by typing it if this is set to true.

  • The step property is used to set the value the pushbuttons increment/decrement the value of the spinbox. The default for this is 1, but it can be changed to something else.

• Checkbox
  The checkbox control is normally used with a logical value, and is designed to show a check if the value is true, and an empty box if it is false.
  • The checkBox has one property that most of the other controls do not (radiobuttons and pushbuttons share this property) -- textLeft -- if this is set to true, the text of the checkbox will appear on the left side of the checkbox. The default is false, which means that the text appears on the right side of the checkbox.

• Radiobutton
  The radiobutton control often confuses people -- this is because the value property returns a logical (true/false) value, but what is stored in the field of the table is the TEXT property of this control. It is possible to use the radiobutton for non-text values, but there is another level of coding that would be necessary to accomplish this (it's called Field Morphing) that we will not get into in this document.

  The purpose of radiobutton controls is to present the user with a limited set of choices for a character field. A really simple example would be setting ice cream flavors, and you only had three: Chocolate, Vanilla or Strawberry. By setting three radioButtons onto a form with the text reading "Chocolate" for the first, "Vanilla" for the second, and "Strawberry" for the third, and datalinking all three of these radioButtons to the same field, the user will only be allowed one of those three choices.

  Tip: use the group property for the FIRST radioButton -- set it to true (if not done for you by the designer). Make sure no other controls appear in the "Z-Order" between the radiobuttons. (The "Z-Order" is the sequence the events are defined in the form's constructor code. You can modify this in the designer through the layout menu, and in the source code directly by cutting and pasting code appropriately.) If you follow this tip you should not have problems with your radiobutton controls behaving properly (for example, a user using the arrow keys will loop through the radiobuttons ...).

  • The radioButton also has a textLeft property -- see the checkBox for details.

• Editor
  The editor control is used for large quantities of text.

  It has some really interesting capabilities, but you must be careful ... some things don't work quite the way you might expect.

  • The dataLink property has the ability to datalink to a memo field (or even a long character field) of a table, but it also has the ability to link to a file.

  • The lineNo property shows the current line number in the editor control. This may be the current line in a file, if you are datalinked to one, but if the editor is not as wide as your file's lines, and the wrap property (see below) is set to the default of "true", then the lineNo may not match ...

  • The columnNo property shows the current column number in the editor control. This is related to lineNo above, and can be used in conjunction to determine where the cursor is on a character by character basis in the editor control. This is new to dB2K.

  • The modify property allows or disallows the user's ability to edit the contents of the editor object's value property.

  • The wrap property is used to wrap text -- it defaults to true, but you can set it to false. If you do, you will automatically get a horizontal scrollBar at the bottom of the editor (see the scrollBar property below).

  • The marginHorizontal and marginVertical properties deal with how close to the edge of the editor control the actual text will appear.

  • The popupEnable property allows a special popup for memos to appear on a right mouse click. It includes some useful things, like a find dialog to find text, and more. Interesting note, the last item in the popup "Show Format Toolbar" can ... er ... be interesting. It allows the user to insert HTML into the editor (see "evalTags" below) -- the problem is, once the HTML is inserted, there is no way to remove it, and it becomes part of the text -- even if you set the "evalTags" property to false, it's pretty much impossible to remove the HTML from a memo field. If the form is MDI (Multiple Document Interface -- opened with the Open() method), this toolbar is available, if the form is SDI (Single Document Interface -- opened with readModal()), the toolbar is NOT available.

  • The evalTags property is used to evaluate HTML tags in the editor. If it is set to false (the default is true), then rather than evaluating them, you should see the tags ...

  • The scrollBar property can be used to set vertical and/or horizontal scroll bars on, set to "auto" (use them if needed) or turn them off completely.

  • The Editor has finally, in release 2.2 of dBASE Plus got a colorHighlight property, which is used to define the color of the editor when it has focus. If you are using versions of dBASE earlier than dBASE Plus 2.2 you can simulate this by using the editor control's onGotFocus event and changing the colorNormal to a different setting, and in the onLostFocus event setting it back to what it was before.

  Editors and the Rowset's autoEdit Property
  The editor control may ignore the rowset's autoEdit property, which can be a bit disconcerting and frustrating. If you add the following code to the editor control's key event, you can avoid this particular problem:

         function key
            /* 
                  This code by Gary White is provided to
                  get around a problem with rowsets that
                  have the autoEdit property set to false,
                  and editors. The editor seems to be immune
                  to this property once you make a change
                  in it -- if you then save or abandon, you
                  can actually edit the contents of the editor
                  object ...              
               */
               // this     = editor
               // dataLink = field
               // parent   = fieldArray
               // parent   = rowset
               if type( "this.datalink.parent.parent" ) # "U"
                  r = this.datalink.parent.parent
                  if r.autoEdit == false  and ;
                     ( r.state # 2 and r.state # 3 )
                     return 0
                  endif
               endif
      

  HTML and Editor Controls
  Editor controls, as mentioned elsewhere, can be used to display text formatted with HTML.

  One item of interest here is that the editor control can actually use the HTML <IMG> tag. However, please note that HTML itself does not know anything about tables, rowsets, fields, and so on, so you cannot directly set the image source to look at a field.

  However, if what you need to do is embed an image into an editor control's HTML that is stored in a table, what you can do is use the binary field object's copyToFile() method, and then in the editor control set the <IMG> tag's SRC to point to that file. You might have to do this sort of thing by using the rowset's onNavigate or canNavigate event(s) to copy the file out to disk and then delete it. This should give you a pointer or two, though.

  Note that you can drag & drop an image into a memo editor and the appropriate HTML tag will be stored in the memo.

  Please note that many other HTML tags can be used as well in your HTML in the editor, but not all. These tags include lists (<UL> <OL>), header, font (useful for colors), italic, bold, underline, etc ...

  See the Text control and information about HTML there for more details on what is available ...

• Listbox
  Listboxes are quite useful, in that they can be used to list the contents of an array, or the contents of a field in a table, and even more fun, they can be used to list the contents of a field in the table you are editing, and be used to move the row pointer (this may not be desirable, but it is an interesting effect ...).
  • The dataSource property has several options here. The dataSource is the source of information for the items listed.
    • Array -- If you are using an array, you must include the word "Array" (case is not important), followed either by a literal array (i.e., {"Item 1", "Item 2", etc.}) or the name of the array object (i.e., form.listbox1.myarray or aMyArray ...).
    • Field -- you can display the contents of a field from a table. If this is the "current" table (i.e., the one that other controls are set to "edit"), selecting an element in the listbox will actually move the record pointer ... this may not be what you wanted to have happen.
    • File -- must have a filename skeleton -- it is possible to list all files in a directory (*.*) or files of a specific type (*.TXT) and so on.
    • Structure -- this creates a listing of all the fields in the active table -- the table that is the "active" one for the form. Note: This only works if you are using XDML syntax to access tables. There is an example in the samples for this How To document that shows how to get an array of fields using OODML syntax, and set that as the dataSource for a listbox.
    • Tables -- creates a listing all the tables in the current database (if using local tables, *.DBF, *.DB). Note: this option does not currently appear to work in the 32-bit version of dBASE.
    As you can see, the dataSource can open up the possibilities for use of the listbox rather widely.

    Tip: If you (or the user) make any changes to the dataSource, those changes are not automatically reflected. The dataSource is read when the form is instantiated and is not re-read unless you specifically tell it to do so. You can accomplish this by simply issuing the following command (using the name of your listbox):

                 form.listbox1.dataSource += ""
            

    This causes the listbox to re-evaluate the dataSource property ... Note that this would be called in the onChange event of the control that changed the dataSource of the listbox.

  • The multiple property allows your user to select multiple elements from the list. This is done by holding the CTRL key and clicking on multiple items, or by clicking on the first item and holding down the SHIFT key while clicking the last item to select a contiguous range of items. If you allow this, you need to be able to see what they selected. The value property is not useful for this, instead the selected() method is used.

    If you use the multiple property, the selected method takes on a different meaning than it does if you have multiple set to false. This method will actually give you a reference to an array of selected elements in the listbox.

    The array is accessed like:

                   form.listbox1.selected()[ index ]
               

    (index is the array's index, i.e., 1 would be the first element in the array)

    If your listbox.dataSource is pointing to a field in a table, the value returned by the selected() method will be a bookmark for the rowset. This can be a bit disconcerting, as you might have expected to see the value of a specific item. In order to do that, you would need to move to the row in the rowset. You could use code similar to:

                  clear
                  // need to do this, or the listbox gets updated
                  // as we navigate
                  form.rowset.notifyControls := false
                  a = form.listbox1.selected()
                  // loop through the array defined by the selected()
                  // method
                  for i = 1 to a.size
                      // go to bookmark:
                      form.rowset.goto( a[i] )
                      // display value
                      ? form.rowset.fields["Name"].value
                  next
                  // turn on the notify, or things get really weird
                  form.rowset.notifyControls := true
               

  • The sorted property is used for any dataSource that is not a field (the data will display in whatever sequence the table is sorted in that case). If the sorted property is false, the dataSource will be listed in "natural" sequence, otherwise it will be sorted.

  • The curSel property is a numeric reference to the currently selected item. If you want to show the prompt, use the value property (unless you are using the multiple property and selected method -- see above ...)

  • The value property shows the currently highlighted item (even if not selected in the case of the multiple property being set to true).

  • The onSelChange event is fired when the user selects a different prompt (with the mouse or by using the keyboard to move the prompt up and down).

  • The count method will return the number of elements in the listbox's datasource. This is handy if you do not know in advance how many items will be listed, and need to know this for programmatic reasons.

  • The transparent property is used to make a listbox transparent -- this means that the background of the form shows through the listbox. There is one effect that you, as a developer may find confusing at first -- when you set transparent to true for a listbox, there is no background for the listbox. This means that the background color of both the colorNormal and colorHighlight properties is ignored. You need to be sure that your colorHighlight property uses a color that stands out dramatically from the colorNormal property and the background of the form. This is new to dBASE Plus release 2.2.

  • The selected method will display the prompt of the currently selected item in the datasource (useful for programmatic work, perhaps in the onSelChange event), or it can be used to tell if a specific item has been selected. For example, you could check to see if the first item in your listbox was selected by calling this method in the following manner:

              if form.listbox1.selected( 1 )
                 // do something
              endif
           

    Tips:
    • If you have a large dataSource, and wish to pre-select an item (use the value property) that does not appear at the top of the list, you can use some API calls to do this. See the dBASE Users' Function Library Project in the Knowledgebase to get hold of this code.
    • In the same library of code is an example of using code to select items in one listbox and move them to another. (mover.cc)
    • And yet again in the same library is an example of using API calls to drag elements in a listbox up and down changing their position in the datasource.

  • Colors -- It should be noted that in dB2K, there is no way to change the background color of a listbox that does not have any list items in it -- the area is a dark grey. In dBASE Plus this has been changed and the background color of the colorNormal property is used for the complete background of the listbox control. What this means is if you use a colorNormal of "white/blue" -- that is a white foreground, and a blue background, then the whole listbox will be blue, and the text of the items in the listbox will be white. The background area will only change if the colorNormal property changes, or if your colorHighlight property changes the background for the currently selected item(s). Also note that if the transparent property is true, all of this discussion is moot, because the listbox will use the color or image of the underlying form for the background.

  Sample Form:

  • LISTBOX.WFM -- this simple form demos using a table's fields in OODML for the dataSource of a Listbox.

• Combobox
  The Combobox may seem like it's related to the listbox, but it's really related more to the entryfield. It is an entryfield object with a pushbutton used to "drop down" a list of selections (from the dataSource).

  The combobox control can be quite useful for a lot of different situations, and can be automatically used if you set up a field in a table with the lookupSQL property.

  ---

  The field object's lookupSQL property can be handy -- it gives you the ability to do an automatic lookup on another table (and even the same table, but that can get very strange and is not recommended). Briefly, you can set this as a custom property of the field you wish to lookup in another table, or you can set it in the DataModule or Query object in the query's onOpen (or canOpen) event.

  For a lookupSQL to work properly, you must have a key value that is stored in the main table (the one you are working in) that matches a key value in the lookup table. The lookup table would ideally have at least one other field.

  What you are doing is showing the user the value of the second field (or a calculated field -- we won't get into that here) in a combobox, but STORING IN THE FIELD the key value that matches what appears in the combobox.

  An example of this would be something like the following: A customer table stores state ids (for US states), but when you look at a form that displays the customers, the combobox shows the full name of the state. The actual value stored in the customer table would be the state id, not the full name of the state, but what the user would see is the full name of the state.

  NOTE: Do NOT set a DataSource for a combobox that is created by the software for use with a lookupSQL field -- the datasource is created automatically for you, and anything you do will be overridden.

  More details on this can be found in online help.

  ---

  • The dataSource property is discussed in ListBox above. The only difference is that if you use a field for the dataSource you will run into a couple of limitations. The first is that you can only load a limited number of rows (max is somewhere around 2000?), and the second is that this is not dynamic -- once the dataSource is loaded into memory, it does not get updated -- if changes are made to the table you are using the field from, it is not automatically refreshed in the combobox. You can, however reassert the datasource:

                   form.combobox1.dataSource += ""
               

    The code above (using your own combobox name appropriately) will cause the datasource to be re-evaluated ... (the actual dataSource reference is contained in the property, adding a null character string will force the reassertion).

    NOTE: See above in the lookupSQL insert -- if you are using lookupSQL with a combobox (default behavior) then do NOT set a datasource ...

  • The autoDrop property is used to cause the combobox to automatically drop down when the combobox gains focus. The default is false, if you set it to true, when the user sets focus (tab, or with the mouse) the drop down will automatically drop.

  • The dropDownHeight property is used to change the height -- the default value is 6 lines.

  • The dropDownWidth property is used to set the width -- if set to zero (the default) it will show the width of the combobox itself, otherwise it will display as wide as you define it. This uses the metrics of the form that the combobox is on.

  • The style property is used to define which style combobox to use. The default is "1 - DropDown", which means that the user must click the button to cause the list to drop. You can set it to "0 - Simple" which means that the drop down list appears automatically, and to "2 - DropDownList" which means that a) the user must click the button to see the list (unless the autoDrop property is set to true), and b) the user cannot enter a value into the entryfield portion of the combobox, which they can do with styles of zero and one.

  • The ComboBox has finally, in release 2.2 of dBASE Plus got a colorHighlight property, which is used to define the color of the combobox when it has focus. If you are using versions of dBASE earlier than dBASE Plus 2.2 you can simulate this by using the combobox control's onGotFocus event and changing the colorNormal to a different setting, and in the onLostFocus event setting it back to what it was before.

  Sample Form:

  • COMBOBOX.WFM -- this simple form demos the ability to have one combobox affect the datasource of the second. No tables are used for it, but the heading and other comments in the form's source code discuss using tables instead of arrays ...