wiki:EasyGuiControls

Controls

Controls, sometimes known as dialog items or widgets, are subviews that manage redisplay and user interactions in stylized ways. The following controls are predefined:

Separator Line view

separator-line-view (subview view-orientation-mixin) [class]

A line (horizontal or vertical) that can be used to visually separate portions of a dialog. When specifying the view size, one of width or height should be 1 (which is the default, so this can be achieved by only specifying one of width or height).

Progress Bar view

progress-bar-view (subview view-orientation-mixin view-range-mixin) [class]

Shows progress towards completion of a lengthy operation. A progress bar has a view-minimum, view-maximum, and the current view-value, which should be programatically incremented from the minimum to the maximum. As a special case, view-value may be nil to indicate that the total length of any operation is not known, in which case the minimum and maximum are ignored and the progress bar displays as a spinning spiral cylinder that indicates that something is happening but gives no indication how soon the operation will complete.

Slider view

slider-view (subview view-orientation-mixin view-range-mixin view-mouse-tracker-mixin) [class]

Lets the user make a selection along a continuous range of allowable values. A slider has a view-minimum, view-maximum, and the current view-value, which ranges between the minimum and the maximum in response to user moving the slider. If the slider has a non-nil view-mouse-tracker, it will be called as the indicator is dragged, with the view-value updated appropriately. Additional initargs:

:slider-indicator -- sets the shape of the slider indicator, one of :right, :left, :up, :down, :none

:slider-tick-count -- sets the number of tick marks to draw on the slider bar, an integer value between and #xFFFF, or nil (the default) for no tick marks. If non-nil, the size of the view must be large enough to accommodate the tick marks.

(slider-indicator slider-view) [method]

Returns the shape of the slider indicator, one of :right, :left, :up, :down for an indicator that points in the corresponding direction, or :none for a round indicator.

(slider-tick-marks slider-view) [method]

Returns the number of tick marks in slider-view, on nil if the slider doesn't have tick marks.

Scroll Bar view

scroll-bar-view (subview view-orientation-mixin view-range-mixin view-mouse-tracker-mixin) [class]

Scroll bars are used to show parts of a document. A scroll bar has a view-minimum, view-maximum and the current view-value which ranges between the minimum and the maximum in response to the user moving the scroller (the movable oblong part), and represents the relative location, in the whole document, of the portion that can be seen. The size of the scroller is proportional to how much of the document is visible. If the slider has a non-nil view-mouse-tracker, it will be called as the scroller is dragged, with the view-value updated appropriately. Additional initargs:

:scroll-bar-scroller-size -- initializes the scroller size, see set-scroll-bar-scroller-size.

(set-scroll-bar-scroller-size scroll-bar-view size) [method]

Sets the size of the currently visible part of the document, expressed in terms of the same units as used for minimim and maximum. This determines the size of the scroller.

(scroll-bar-scroller-size scroll-bar-view) [method]

Returns the size of the currently visible part of the document, expressed in terms of the same units as used for minimim and maximum.

Text Input view

text-input-view (subview view-text-mixin) [class]

Lets the user enter text. Additional initargs:

:text-input-locked -- initializes the text locked state, see lock-text-input

:text-input-multi-line-p -- if true, allows multi-line input.

:text-input-selection-start -- initializes the current selection start offset, see set-text-input-selection

:text-input-selection-end -- initializes the current selection end offset, see set-text-input-selection

TODO: validation

(lock-text-input editable-text-view) [method]

Locks the text in the view so it can't be modified (even though it's still shown as enabled).

(unlock-text-input editable-text-view) [method]

Unlocks the text in the view so it can be modified again.

(text-input-locked-p editable-text-view) [method]

True if text in view is locked.

(text-input-multi-line-p editable-text-view) [method]

True if multi-line input is supported.

(text-input-selection editable-text-view) [method]

Returns two values, the start and end offset of the selection in the text.

(text-input-selection-start editable-text-view) [method]

Returns the start offset of the selection.

(text-input-selection-end editable-text-view) [method]

Returns the end offset of the selection

(set-text-input-selection editable-text-view &key start end)

Sets the selection to the range specified.

Password Text Input view

password-input-view (text-input-view) [class]

Subclass of text-input-view for entering passwords. Echos typein as bullets.

Static Text view

static-text-view (subview view-text-mixin) [class]

Displays text. Additional initargs:

:static-text-truncation -- initializes text truncation style, see set-static-text-truncation.

(set-static-text-truncation static-text-view truncation) [method]

Sets the truncation style for static-text-view to one of :end, :middle or nil. If nil (the default), text wraps to multiple lines instead of truncating, otherwise it's drawn on one line, truncating at the end or in the middle.

(static-text-truncation static-text-view) [method]

Returns the truncation style of static-text-view, one of :end, :middle or nil.

List Box view

list-box-view (subview) [abstract class]

This is an abstract class of scrollable views that display data in rows and columns. It provides all the behavior except storing the data to display. To use it, you should subclass it and define a specialized method on the list-box-cell-text generic function. Additional initargs:

:list-box-dimensions -- initializes the dimensions, see set-list-box-dimensions.

:list-box-selection-type -- the type of selection handling to use, one of :single, :contiguous, or :disjoint.

:list-box-horizontal-scroll-p -- determines whether to have a horizontal scroll bar

:list-box-vertical-scroll-p -- determines whether to have a vertical scroll bar.

:list-box-cell-size -- initializes cell seize, see set-list-box-cell-size.

:list-box-cell-width -- width of each cell, overrides list-box-cell-size

:list-box-cell-height -- height of each cell, overrides list-box-cell-size

:list-box-grow-space-p -- true to indicate that the conrol is draw so that there is room for a size box.

TODO: font style and key filter

TODO: MCL also supports per-cell font and color, because it does the drawing itself

(list-box-cell-text list-box-view cell) [method]

Returns the text contents of the cell in column (point-h cell) and row (point-v cell). The default method returns nil. Subclasses should provide a particular implementation.

(set-list-box-dimensions list-box-view dimensions) [method]

Sets the number of columns in list-box-view to (point-h dimensions) and the number of rows to (point-v dimensions).

(list-box-dimensions list-box-view) [method]

Returns the dimensions of list-box-view as (point column-count row-count).

(set-list-box-visible-dimensions list-box-view dimensions) [method]

Resizes list-box-view so that (point-h dimensions) columns and (point-v dimensions) rows are visible.

(list-box-visible-dimensions list-box-view) [method]

Returns the number of cells visible in the horizontal and vertical dimensions.

(set-list-box-cell-size list-box-view size) [method]

Sets the size of a cell in list-box-view. All cells have the same size. Changing the cell size changes the list-box-visible-dimensions.

(list-box-cell-size list-box-view) [method]

Returns the size of a cell in list-box-view. All cells have the same size.

(list-box-selection-type list-box-view) [method]

Returns the selection type of list-box-view, one of :single, :contiguous, or :disjoint.

(list-box-horizontal-scroll-p list-box-view) [method]

Returns true if list-box-view has a horizontal scroll bar.

(list-box-vertical-scroll-p list-box-view) [method]

Returns true if list-box-view has a vertical scroll bar.

(list-box-scroll-to-cell list-box-view cell) [method]

Scrolls list-box-view so that the cell in column (point-h cell) and row (point-v cell) is in the upper-left corner.

(list-box-scroll-position list-box-view) [method]

Returns the cell in the upper-left corner, represented as a point.

(list-box-cell-select list-box-view cell) [method]

Selects the cell in column (point-h cell) and row (point-v cell).

(list-box-cell-deselect list-box-view cell) [method]

Deselect the cell in column (point-h cell) and row (point-v cell).

(list-box-cell-selected-p list-box-view cell) [method]

True if the cell in column (point-h cell) and row (point-v cell) is selected.

(list-box-selected-cells list-box-view) [method]

Returns a list of all currently selected cells in list-box-view. Each cell is represented by a point.

Array view

array-view (list-box-view) [class]

A type of list box view that displays the elements of a two dimensional array. Additional initargs:

:list-box-array -- initializes the view array, see set-list-box-array.

(set-list-box-array array-view array) [method]

Sets the array displayed in array-view to array, a 2-dimensional array. It should not be destructively modified while being used by an array view.

(list-box-array array-view) [method]

Returns the array displayed in array-view. It should not be directly modified while being used by an array view.

(list-box-cell-text array-view cell) [method]

The default array-view method obtains the array element corresponding to cell and converts it to a string using princ-to-string.

Sequence view

sequence-view (list-box-view view-orientation-mixin) [class]

A type of list box view that displays the elements of a sequence, horizontally or vertically. Additional initargs:

:list-box-sequence -- initializes the view sequence, see set-list-box-sequence.

(set-list-box-sequence sequence-view sequence) [method]

Sets the sequence displayed in sequence-view to sequence. sequence can be any Common Lisp sequence type, i.e. a list or a vector. It should not be destructively modified while being used by a sequence view.

(list-box-sequence sequence-view) [method]

Returns the sequence displayed in sequence-view. It should not be directly modified while being used by a sequence view.

(list-box-cell-text sequence-view cell) [method]

The default sequence-view method obtains the sequence element corresponding to cell and converts it to a string using princ-to-string.

Push Button view

push-button-view (subview view-text-mixin view-action-mixin) [class]

Push buttons are rounded rectangles that display the view-text, and when pressed invoke the view-action. Additional initargs:

:default-button-p -- if true, this is the default button. Default buttons are drawn with an outline and may be activated by hitting Return.

:cancel-button-p -- if true, this is the cancel button. This has no visible representation, but does cause the button to play the cancel button theme sound instead of the regular push button theme sound when pressed.

(default-button-p push-button-view) [method]

True if this is the default button.

(cancel-button-p push-button-view) [method]

True if this is the cancel button.

TODO: push buttons with icons -- would need support for icons…

Radio Button view

radio-button-view (subview view-text-mixin view-state-mixin) [class]

Radio buttons are small circles that contain a black dot when they are selected (pushed). The view-text is displayed next to the circle. Radio buttons have a view-state which may be :on, :off, or :mixed, the last indicating that the current setting contains a mix of on and off values. Radio buttons normally occur in groups, i.e. their view-container is a radio-button-group-view, and only one button in a group may be pushed at a time. If the button is not a subview of a radio-button-group-view, pressing it will toggle it on/off.

(view-valid-states radio-button-view) [method]

Returns %%'%%(:on :off :mixed).

Radio Button Group view

radio-button-group-view (subview) [class]

An invisible enclosure for radio buttons. The only view-subviews allowed are radio-button-view's. The radio buttons are automatically set to be mutually exclusive.

(selected-group-radio-button radio-button-group-view) [method]

Returns the currently selected radio button in the group.

Checkbox view

checkbox-view (subview view-text-mixin view-state-mixin) [class]

Checkboxes are small squares that toggle an X mark on and off when clicked. The view-text is displayed next to the square. Checkboxes have a view-state which may be :on, :off, or :mixed, indicating that the current setting contains a mix of on and off values.

(view-valid-states checkbox-view) [method]

Returns %%'%%(:on :off :mixed).

Data Browser view

databrowser-view (...) [class]

TODO: tbd

Pop-up Benus

TODO: tbd

Custom view

custom-view (subview) [class]

Custom views allow you to implement the view's appearance and behavior. Initiargs:

:view-mouse-down-handler -- initializes the mouse-down handler, see set-view-mouse-down-handler.

:view-mouse-up-handler -- initializes the mouse-up handler, see set-view-mouse-up-handler.

:view-key-handler -- initializes the keyboard input handler, see set-view-key-handler.

:view-draw-handler -- initializes the handler for drawing the view, see set-view-draw-handler.

(set-view-mouse-down-handler custom-view handler) [method]

Sets the function to be called when the user clicks inside the view. handler should be a funcallable object (a function or symbol), and it will be called with two arguments, the view and a point indicating the mouse position within the view, in the view's coordinate system.

(view-mouse-down-handler custom-view) [method]

Returns the view's mouse-down handler.

(set-view-mouse-up-handler custom-view handler) [method]

Sets the function to be called when the user releases the mouse. handler should be a funcallable object (a function or symbol), and it will be called with two arguments, the view and a point indicating the mouse position in the view's coordinate system. Note that the mouse might be outside the view on mouse-up.

(view-mouse-up-handler custom-view) [method]

Returns the view's mouse-up handler.

(set-view-key-handler custom-view handler) [method]

Sets the function to be called when the types on the keyboard. handler should be a funcallable object (a function or symbol), and it will be called with two arguments, the view and the key that was entered. TODO: TBD how the “key that was entered” is actually represented -- could be char, or more complex.

(view-key-handler custom-view) [method]

Returns the view's key handler.

(set-view-draw-handler custom-view handler) [method]

Sets the function to be called when the view needs to be drawn. handler should be a funcallable object (a function or symbol), and it will be called with one two arguments, the view and a graphics context. See the Graphics section for information about drawing text and graphics in a view. Note that you should never call this function directly, it is only meant to be invoked in the callback context. To programmatically cause your view to be redrawn, call invalidate-view.

(view-draw-handler custom-view) [method]

Returns the view's draw handler.

TODO: Need to provide utility fns for switching focus so custom views can respond to tab/enter.

TODO: Need to provide protocol for extending view-action-mixin so can do custom controls