Form

Alternative name: Window

Description

The Form (or Window) object is a standard window, on which can be placed other objects (such as buttons, pictures, or edit text fields). You can determine whether or not it is resizable, has close and zoom boxes, and the appearance of the title bar, by setting the border property when you create the window. The basic border styles are:

        0         No border
        1         Standard document window, window not resizable
        2         Resizable document window
        3         Modal-dialog style window
        4         Movable modal-dialog style window
        5         Thin title-bar, non-resizable window
        6         Thin title-bar, resizable window

The optional flags which you can add to these basic values are:

        16        Window includes a Close box
        64        Window includes a Zoom box (under MacOS) 
                  or Minimize/Maximize controls (under Windows or Linux)

You cannot include a Close box if the basic border type is 0, and you cannot include a Zoom box if it is 0, 5 or 6.

Note that, under Linux, the Window Manager determines how the request for a particular border will be interpreted, so the border style you ask for may not be honored. Under some Window Managers, windows are always resizable.

The default value is 2+16+64 = 82 for a Window object.

Window properties

The other main properties of a Window which you are likely to use are:

title: The title which appears in the Window's title bar.

visible: Allows you to make the window visible or invisible

scale: Determines the units used to place controls in the window (inherits from the System object scale when the window is created).

size: The height and width of the window, in the window's own scale.

where: The position and size of the window, in the scale of the System object.

maxsize: Allows you to specify the maximum size of the window

minsize: Allows you to specify the minimum size of the window

bitmap: Read-only property which returns a matrix of the pixels which make up the displayed window's contents. (Not implemented under Linux. Under MacOS 9, valid only if the window is completely visible on screen.)

Window methods

Methods which are useful include:

Open: Open a window which you have previously closed

Close: Close a window, either conditionally or unconditionally

Wait: Makes the window modal (see below)

Draw: Draws geometric shapes and text on the window

Window events

The event handler (callback) properties which are particularly relevant to Window objects are:

onResize: Invoked when the user changes the window's size

onFocus: Invoked when the window gets focus (is activated)

onClose: Invoked when the user wants to close the window

onDestroy: Invoked when the window is destroyed

Creating and Opening of Windows

In order to avoid lots of drawing and moving while creating a window and its child objects, it is always initially created in a hidden state. It is shown (unless explicitly hidden) on the first of the following:

• APL requests input
  
• You call ⎕WE, or (under MacOS) one of the APLX library functions GETEVENT, WAITEVENT or GETEVENTS
  
• You create another window
  
• You explicitly open it using the Open or Show methods
  

Using windows as modal dialogs

The Wait method makes the window display in modal form, i.e. other windows of your application are disabled until the window has closed. For modal dialogs, you should consider using the Dialog object, which is a special case of the Form object in which the borders and background automatically take on the appropriate appearance for a modal dialog on the system on which APLX is running.

Deleting windows

In order to free up memory used by an object, you must ensure it is deleted when you have finished with it. If you created it using ⎕NEW, it will be deleted automatically when the last reference to it is erased from the workspace. (In the example below, this will happen automatically when the function ends, because the variable DEMO which hold the reference to the window is localized).

If you created the window using ⎕WI, there is no explicit reference to the window held in the workspace, so it will not be deleted automatically until the APLX session ends. You therefore need to delete it explicitly, using the Delete method (note that this is not the same as closing the object). You normally only need to do this for the window itself, since all child objects on the window are automatically deleted when you delete the parent.

As a convenience, windows which have no onClose callback defined are automatically deleted if the user closes the window. If you still have a reference to the window in the workspace because you created it using ⎕NEW, the reference will become a reference to an 'Unknown object'.

Example

     ∇DEMO_Form;DEMO
[1]   ⍝ Sample function demonstrating use of the Form object
[2]   ⍝ Set border to 5 (for thin title) plus 16 (Close box)
[3]   DEMO←'⎕' ⎕NEW 'Form' ⋄ DEMO.border←(5+16)
[4]   DEMO.title←'Form Example'
[5]   DEMO.where←4 4
[6]   ⍝
[7]   ⍝ Wait for the user to close the window
[8]   0 0⍴⎕WE DEMO
     ∇

Properties

align anchors aquaadjust autodraw bitmap border caption children class color data doublebuffered dragsource droptarget enabled events extent handle maxsize menuimagelist methods minsize name opened pointer properties scale self size sourceformats targetformats tie units visible where winptr

Methods

Click Clienttoscreen Close Create Delete Draw Focus Hide New Open Paint Resize Screentoclient Send Set Show Trigger Wait

Callbacks

onClick onClose onDblClick onDestroy onDragDrop onDragEnd onDragEnter onDragLeave onDragOver onDragStart onFocus onHide onMenu onMouseDown onMouseMove onMouseUp onMove onOpen onPaint onResize onSend onShow onUnFocus