HomeWare 14/HOMEWARE14.bin/os2/lbasic04.arj/WINDOWS.TXT

Text File | 1994-02-18 | 27KB | 728 lines

(You may want to pick a smaller font, or turn word-wrap off in your OS/2
 system editor if this file is hard to read.)

  WINDOW DEVICE COMMANDS
  ---------------------------------------------------------------------------

  In Liberty BASIC windows are treated like files, and we can refer
  to anything in this class as a BASIC 'Device'.  To open a window
  we use the OPEN statement, and to close the window we use the
  CLOSE statement.  To control the window we 'print' to it, just as
  we would print to a file.  The commands are sent as strings to the
  device.  As a simple example, here we will open a graphics window,
  center a pen (like a Logo turtle), and draw a simple spiral.  We
  will then pause by opening a simple dialog.  When you confirm the
  exit, we will close the window:

    button #graph, Exit, [exit], LR, 5, 5    'window will have a button
    open "Example" for graphics as #graph    'open graphics window
    print #graph, "up"                     'make sure pen is up
    print #graph, "home"                   'center the pen
    print #graph, "down"                   'make sure pen is down
    for index = 1 to 30                    'draw 30 spiral segments
      print #graph, "go "; index           'go foreward 'index' places
      print #graph, "turn 118"             'turn 118 degrees
    next index                             'loop back 30 times
    print #graph, "flush"                  'make the image 'stick'

  [inputLoop]
    input b$ : goto [inputLoop]            'wait for button press

  [exit]
    confirm "Close Window?"; answer$       'dialog to confirm exit
    if answer$ = "no" then [inputLoop]     'if answer$ = "no" loop back
    close #graph

  end



  WINDOW TYPES:
  -------------------------------------------------------------------------

  Liberty BASIC provides different kinds of window types, to which you
  can add as many buttons as needed.  Here's a list of the different kinds:

    graphics
        - open a graphic window
    graphics_fs
        - open a graphic window full screen (size of the screen)
    graphics_nsb
        - open a graphic window w/no scroll bars
    graphics_fs_nsb
        - open a graphic window full screen, w/no scroll bars

    dialog
        - open a dialog box window


  The way that you would specify what kind of window to open would be
  as follows:

    open "Window Title" for type   as #handle

  where type  would be one of the above descriptors.


  CONTROLLING SIZE AND PLACEMENT OF WINDOWS
  ----------------------------------------------------------------------------

  The size and placement of any window can be easily determined before
  it is opened in Liberty BASIC (except for any window type with a _fs in its
  descriptor).  If you do choose not to specify the size and placement of
  the windows that your programs open, Liberty BASIC will pick default sizes.
  However, for effect it is often best that you exercise control over this matter.

  There are four special variables that you can set to select the size and
  placement of your windows, whether they be text, graphics, or
  spreadsheet:

          UpperLeftX, UpperLeftY, WindowWidth, and WindowHeight

  Set UpperLeftX and UpperLeftY to the number of pixels from the
  upper-left corner (IN OS/2, FROM THE LOWER LEFT-CORNER) of the screen to
  position the window.  Often determining the distance from the upper-left
  corner of the screen is not as important as determining the size of the
  window.

  Set  WindowWidth and WindowHeight to the number of pixels wide and
  high that you want the window to be when you open it.

  Once you have determined the size and placement of your window, then
  open it.  Here is an example:


  [openStatus]

      UpperLeftX = 32
      UpperLeftY = 32
      WindowWidth = 190
      WindowHeight = 160

      open "Status Window" for dialog as #stats


  This will open a window 32 pixels from the corner of the screen, and with
  a width of 190 pixels, and a height of 160 pixels.



  BUTTONS
  ---------------------------------------------------------------------------

 Buttons are easily added to Liberty BASIC windows.  The format is simple:

    button #handle, "Label", [branchLabel], corner, distX, distY
    open "A Window!" for graphics as #handle

  By placing at least one button statement before  the open statement, we can
  add button(s) to the window.  Let's examine each part of the button statement:

    #handle - This needs to be the same as the handle of the window.

    "Label" - This is the text displayed on the button.  If only one word is used,
                          then the quotes are optional.

    [branchLabel] - This controls what the button does.  When the user clicks
                                  on the button, then program execution continues at
                                  [branchLabel] as if the program had encountered a
                                  goto [branchLabel] statement.

    corner, distX, distY - Corner is used to indicate which corner of the
                                   window to anchor the button to.  DistX and distY
                                   specify how far from that corner in x and y to place
                                   the button.  The following values are permitted for
                                   corner:

                      UL - Upper Left Corner
                      UR - Upper Right Corner
                      LL - Lower Left Corner
                      LR - Lower Right Corner

  Whenever a running program sits idle at an input statement, it is possible
  for a button-press to effect some action.  If any button is pressed while
  the program is busy doing something else, the button-press will be
  buffered and read later when an input statement is encountered.



  GRAPHICS
  ---------------------------------------------------------------------------------------

(IN THIS BETA VERSION, NOT ALL OF THE LISTED COMMANDS ARE COMPLETELY
SUPPORTED)

  Because graphics can involve many detailed drawing operations,
  Liberty BASIC does not force you to use just one print # statement
  for each drawing task.  If you want to perform several operations
  you can use a single line for each as such:

    print #handle, "cls"
    print #handle, "fill black"
    print #handle, "pen up"
    print #handle, "home"
    print #handle, "pen down"
    print #handle, "north"
    print #handle, "go 50"

  Or if you prefer:

    print #handle, "cls ; fill black ; pen up ; home ; pen down ; north ; go 50"

  will work just as well, and executes slightly faster.


  print #handle, "\text"

    Display text at the current pen position.  Each additional \ in the
    text will cause a carraige return and line feed.  Take for example,
    print #handle, "\text1\text2" will cause text1 to be printed at the
    pen position, and then text2 will be displayed directly under text1.


  print #handle, "cls"

    Clear the graphics window to white, erasing all drawn elements


  print #handle, "fill COLOR"

    Fill the window with COLOR.  For a list of accepted colors see
    the color command below.


  print #handle, "up"

    Lift the pen up.  All go or goto commands will now only move the
    pen to its new position without drawing.  Any other drawing
    commands will simply be ignored until the pen is put back down.


  print #handle, "down"

    Just the opposite of up.  This command reactivates the drawing
    process.


  print #handle, "color COLOR"

    Set the pen's color to be COLOR.

    Here is a list of valid colors (in alphabetical order):

      black, blue, brown, cyan, darkblue, darkcyan, darkgray,
      darkgreen, darkpink, darkred, green, lightgray, palegray,
      pink, red, white, yellow

  print #handle, "backcolor COLOR"

    This command sets the color used when drawn figures are filled with a
    color.  The same colors are available as with the color command above.

  print #handle, "goto X Y"

    Move the pen to position X Y.  Draw if the pen is down.


  print #handle, "place X Y"

    Position the pen at X Y.  Do not draw even if the pen is down.


  print #handle, "go D"

    Go foreward D distance from the current position, and going in the
    current direction.


  print #handle, "north"

    Set the current direction to 270 (north).  Zero degrees points to the
    right (east), 90 points down (south), and 180 points left (west).


  print #handle, "turn A"

    Turn from the current direction using angle A and adding it to the
    current direction.  A can be positive or negative.


  print #handle, "line X1 Y1 X2 Y2"

    Draw a line from point X1 Y1 to point X2 Y2.  If the pen is up, then
    no line will be drawn, but the pen will be positioned at X2 Y2.


  print #handle, "posxy"

    Return the position of the pen in x, y.  This command must be followed by:

      input #handle, xVar, yVar

    which will assign the pen's position to xVar & yVar


  print #handle, "size S"

    Set the size of the pen to S.  The default is 1.  This will affect the
    thickness of lines and figures plotted with most of the commands
    listed in this section.


  print #handle, "flush"

    This ensures that drawn graphics 'stick'.  Make sure to issue this
    command at the end of a drawing sequence to ensure that when the
    window is resized or overlapped and redrawn, its image will be
    retained.  To each group of drawn items that is terminated with flush,
    there is assigned a segment ID number.  See segment below.


  print #handle, "print"

    Send the plotted image to the Windows Print Manager for output.


  print #handle, "font facename width height"

    Set the pen's font to the specified face, width and height.  If an
    exact match cannot be found, then Liberty BASIC will try to find a
    close match, with size being of more prominance than face.


  print #handle, "circle r"

    Draw a circle with radius r at the current pen position.


  print #handle, "circlefilled r"

    Draw a circle with radius r, and filled with the color specified using
    the command backcolor (see above).


  print #handle, "box x y"

    Draw a box using the pen position as one corner, and x, y as the
    other corner.  print #handle, "boxfilled x y"

    Draw a box  using the pen position as one corner, and x, y as the other corner.
    Fill the box with the color specified using the command backcolor (see above).


  print #handle, "ellipse w h"

    Draw an ellipse at the pen position of width w and height h.


  print #handle, "ellipsefilled  w h"

    Draw an ellipse at the pen position of width w and height h.  Fill the ellipse
    with the color specified using the command backcolor (see above).


  print #handle, "segment"

    This causes the window to return the segment ID of the most recently
    flushed drawing segment.  This segment ID can then be retrieved
    with an input #handle, varName and varName will contain the segment
    ID number.  Segment ID numbers are useful for manipulating different
    parts of a drawing.  For an example, see delsegment below.


  print #handle, "delsegment n"

    This causes the drawn segment identified as n to be removed from the
    window's list of drawn items.  Then when the window is redrawn the
    deleted segment will not be included in the redraw.


  print #handle, "redraw"

    This will cause the window to redraw all flushed drawn segments.  Any
    deleted segments will not be redrawn (see delsegment above).  Any items
    drawn since the last flush will not be redrawn either, and will be lost.


  print #handle, "discard"

    This causes all drawn items since the last flush to be discarded, but does not
    not force an immediate redraw, so the items that have been discarded will
    still be displayed until a redraw (see above).


print #handle, "trapclose branchLabel"
(NOT SUPPORTED IN OS/2 v0.2 BETA)

    This will tell Liberty BASIC to continue execution of the program at
    branchLabel if the user double clicks on the system menu box
    or pulls down the system menu and selects close (see buttons1.bas
    example below).


{Illustration was here}


  The trapclose code in buttons1.bas looks like this:

    open "This is a turtle graphics window!" for graphics_nsb as #1
    print #1, "trapclose [quit]"

[loop]    ' stop and wait for buttons to be pressed
    input a$
    goto [loop]


  And then the code that is executed when the window is closed looks like this:

[quit]
    confirm "Do you want to quit Buttons?"; quit$
    if quit$ = "no" then [loop]
    close #1
    end


  Since this only works when the program is halted at an input statement, the
  special variable TrapClose permits detection of the window close when you
  are running a continuous loop that doesn't stop to get user input.  As long as
  TrapClose <> "true", then the window has not been closed.  Once it has been
  determined that TrapClose = "true", then it must be reset to "false" via the
  BASIC LET statement.  See clock.bas for an example.

  print #handle, "when event branchLabel"

    This tells the window to process mouse events.  These events occur
    when someone clicks, double-clicks, drags, or just moves the mouse
    inside of the graphics window.  This provides a really simple mechanism
    for controlling flow of a program which uses the graphics window.  For
    an example, see the program draw1.bas.

    Sending print #handle, "when leftButtonDown [startDraw]" to any
    graphics window will tell that window to force a goto [startDraw] when
    the mouse points inside of that window and someone press the left mouse
    button down.

    Whenever a mouse event does occur, Liberty BASIC places the x and y
    position of the mouse in the variables MouseX, and MouseY.  The
    values will represent the number of pixels in x and y the mouse was from
    the upper left corner of the graphic window display pane.

    If the expression print #handle, "when event" is used, then trapping
    for that event is discontinued.  It can however be reinstated at any time.

    Events that can be trapped:

      leftButtonDown - the left mouse button is now down
      leftButton Up - the left  mouse button has been released
      leftButtonMove - the mouse moved while the left button is down
      leftButtonDouble - the left button has been double-clicked
      rightButtonDown - the right mouse button is now down
      rightButton Up - the right  mouse button has been released
      rightButtonMove - the mouse moved while the right button is down
      rightButtonDouble - the right button has been double-clicked
      mouseMove - the mouse moved when no button was down


  PROGRAMMING DIALOG BOXES
  ---------------------------------------------------------------------------------------

  Using windows of type dialog, we can add several kinds of objects (called
  child windows) in addition to buttons and menus to our Liberty BASIC
  programs.  These let us add functionality and visual appeal.

  Below are kinds of child windows we can add:

  LISTBOX
  ---------------------------------------------------------------------------------------

  Listboxes in Liberty BASIC can be added to any  windows that are of type
  graphics, window, and dialog.  They provide a list selection capability to your
  Liberty BASIC programs.  You can control the contents, position, and size
  of the listbox, as well as where to transfer execution when an item is selected.
  The listbox is loaded with a collection of strings from a specified string array,
  and a reload command updates the contents of the listbox from the array
  when your program code changes the array.


  Here is the syntax:

  LISTBOX #handle.ext, array$(, [branchLabel], xPos, yPos, wide, high

    #handle.ext  -  The #handle part of this item needs to be the same as the
                handle of the window you are adding the listbox to.  The .ext
                part needs to be unique so that you can send commands to the
                listbox and get information from it later.

    array$(  -  This is the name of the array (must be a string array) that contains
                the contents of the listbox.  Be sure to load the array with
                strings before you open the window.  If some time later you
                decide to change the contents of the listbox, simply change
                the contents of the array and send a reload command.

    [branchLabel]  -  This is the branch label where execution begins when
                the user selects an item from the listbox by double-clicking.
                Selection by only single clicking does not cause branching
                to occur.

    xPos & yPos  -  This is the distance in x and y (in pixels) of the listbox from
                the upper-left corner of the window.

    wide & high  -  This determines just how wide and high (in pixels) the
                listbox is.


    Here are the commands for listbox:


  print #handle.ext, "select string"

    Select the item the same as string and update the display.


  print #handle.ext, "selectindex i"

    Select the item at index position i and update the display.

  print #handle.ext, "selection?"

    Return the selected item.  This must be followed by the statement:

      input #handle.ext, selected$

    This will place the selected string into selected$.  If there is no selected
    item, then selected$ will be a string of zero length (a null string).


  print #handle.ext, "reload"

    This will reload the listbox with the current contents of its array and will
    update the display.


      ' Sample program.  Pick a contact status

        options$(0) = "Cold Contact Phone Call"
        options$(1) = "Send Literature"
        options$(2) = "Follow Up Call"
        options$(3) = "Send Promotional"
        options$(4) = "Final Call"

        listbox #status.list, options$(, [selectionMade], 5, 35, 250, 90
        button #status, Continue, [selectionMade], UL, 5, 5
        button #status, Cancel, [cancelStatusSelection], UR, 15, 5
        WindowWidth = 270 : WindowHeight = 180
        open "Select a contact status" for window as #status

      input r$

  [selectionMade]
      print #status.list, "selection?"
      input #status.list, selection$
      notice selection$ + " was chosen"
      close #status
      end

  [cancelStatusSelection]
      notice "Status selection cancelled"
      close #status
      end

  Control of the listbox in the sample program above is provided by printing
  commands to the listbox, just as with general window types in Liberty BASIC.
  We gave the listbox the handle #status.list, so to find out what was selected, we
  use the statement print #status.list, "selection?".  Then we must perform an
  input, so we use input #status.list, selection$, and the selected item is placed
  into selection$.  If the result is a string of length zero (a null string), this means
  that there is no item selected.

  COMBOBOX
  ---------------------------------------------------------------------------------------

  Comboboxes are a lot like listboxes, but they are designed to save space.
  Instead of showing an entire list of items, they show only the selected one.  If
  you don't like the selection, then you click on its button (to the right), and a list
  appears.  Then you can browse the possible selections, and pick one if so
  desired.  When the selection is made, the new selection is displayed in place of
  the old.  If you don't want to make a new selection, just click on the combobox's
  button again, and the list will disappear.

  Comboboxes in Liberty BASIC can be added to any  windows that are of type
  graphics, window, and dialog.  They provide a list selection capability to your
  Liberty BASIC programs.  You can control the contents, position, and size
  of the combobox, as well as where to transfer execution when an item is
  selected.  The combobox is loaded with a collection of strings from a specified
  string array,  and a reload command updates the contents of the combobox from
  the array when your program code changes the array.


  Here is the syntax:

  COMBOBOX #handle.ext, array$(, [branchLabel], xPos, yPos, wide, high

    #handle.ext  -  The #handle part of this item needs to be the same as the
                handle of the window you are adding the listbox to.  The .ext
                part needs to be unique so that you can send commands to the
                listbox and get information from it later.

    array$(  -  This is the name of the array (must be a string array) that contains
                the contents of the listbox.  Be sure to load the array with
                strings before you open the window.  If some time later you
                decide to change the contents of the listbox, simply change
                the contents of the array and send a reload command.

    [branchLabel]  -  This is the branch label where execution begins when
                the user selects an item from the listbox by double-clicking.
                Selection by only single clicking does not cause branching
                to occur.

    xPos & yPos  -  This is the distance in x and y (in pixels) of the listbox from
                the upper-left corner of the window.

    wide & high  -  This determines just how wide and high (in pixels) the
                listbox is.  Height refers to how far down the selection list
                reaches when the combobox's button is clicked, not to the
                size of the initial selection window.


    Here are the commands for combobox:


  print #handle.ext, "select string"

    Select the item the same as string and update the display.

  print #handle.ext, "selectindex i"

    Select the item at index position i and update the display.


  print #handle.ext, "selection?"

    Return the selected item.  This must be followed by the statement:

      input #handle.ext, selected$

    This will place the selected string into selected$.  If there is no selected
    item, then selected$ will be a string of zero length (a null string).


  print #handle.ext, "reload"

    This will reload the listbox with the current contents of its array and will
    update the display.


  For a sample program, see the included file dialog3.bas.

  TEXTBOX
  ---------------------------------------------------------------------------------------

  The textbox command lets you add a single item, single line text entry/editor
  box to your windows.  It is useful for generating forms in particular.

  The syntax for textbox is simply:

  TEXTBOX #handle.ext, xpos, ypos, wide, high

  #handle.ext  -  The #handle part must be the same as for the window you
                are adding the textbox to.  The .ext part must be unique for
                the textbox.

  xpos & ypos  -  This is the position of the textbox in x and y from the upper-
                left corner of the window.

  wide & high  -  This is the width and height of the textbox in pixels.


  Textbox only understands two commands.  These are:

    print #handle.ext, "a string"

      This sets the contents of the textbox to be "a string".


    print #handle.ext, "!contents?"

      This fetches the contents of the textbox.  This must be followed by:

    input #handle.ext, varName$

      The contents will be placed into varName$


  ' sample program

    textbox #name.txt, 20, 10, 260, 25
    button #name, "OK", [titleGraph], LR, 5, 0
    WindowWidth = 350 : WindowHeight = 90
    open "What do you want to name this graph?" for window_nf as #name
    print #name.txt, "untitled"

[mainLoop]
    input wait$

[titleGraph]
    print #name.txt, "!contents?"
    input #name.txt, graphTitle$
    notice "The title for your graph is: "; graphTitle$
    close #name
    end

  STATICTEXT
  ---------------------------------------------------------------------------------------

  Statictext lets you place instructions or labels into your windows.  This is most
  often used with a textbox to describe what to type into it.

  The syntax of this command is:

  STATICTEXT #handle, "string", xpos, ypos, wide, high

  #handle  -  This must be the same as the #handle of the window you are
                adding the statictext to.

  "string"  -  This is the text component of the statictext.

  xpos & ypos  -  This is the distance of the statictext in x and y (in pixels) from
                the upper-left corner of the screen.

  wide & high  -  This is the width and height of the statictext.  You must specify
                enough width and height to accomodate the text in "string".


    'sample program

    statictext #member, "Name", 10, 10, 40, 18
    statictext #member, "Address", 10, 40, 70, 18
    statictext #member, "City", 10, 70, 60, 18
    statictext #member, "State", 10, 100, 50, 18
    statictext #member, "Zip", 10, 130, 30, 18

    textbox #member.name, 90, 10, 180, 25
    textbox #member.address, 90, 40, 180, 25
    textbox #member.city, 90, 70, 180, 25
    textbox #member.state, 90, 100, 30, 25
    textbox #member.zip, 90, 130, 100, 25

    button #member, "&OK", [memberOK], UL, 10, 160

    WindowWidth = 300 : WindowHeight = 230
    open "Enter Member Info" for dialog as #member

    input r$

[memberOK]
    print #member.name, "!contents?" : input #member.name, name$
    print #member.address, "!contents?" : input #member.address, address$
    print #member.city, "!contents?" : input #member.city, city$
    print #member.state, "!contents?" : input #member.state, state$
    print #member.zip, "!contents?" : input #member.zip, zip$
    cr$ = chr$(13)
    note$ = name$ + cr$ + address$ + cr$ + city$ + cr$ + state$ + cr$ + zip$
    notice "Member Info" + cr$ + note$

    close #member
    end