Changes between Initial Version and Version 1 of EasyGuiControls


Ignore:
Timestamp:
08/30/08 06:36:25 (6 years ago)
Author:
zzkt
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • EasyGuiControls

    v1 v1  
     1= Controls = 
     2 
     3Controls, sometimes known as dialog items or widgets, are subviews that manage redisplay and user interactions in stylized ways. The following controls are predefined: 
     4 
     5== Separator Line view == 
     6 
     7{{{separator-line-view (subview view-orientation-mixin) [class]}}} 
     8 
     9A 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). 
     10 
     11== Progress Bar view == 
     12 
     13{{{progress-bar-view (subview view-orientation-mixin view-range-mixin) [class]}}} 
     14 
     15Shows 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. 
     16 
     17== Slider view == 
     18 
     19{{{slider-view (subview view-orientation-mixin view-range-mixin view-mouse-tracker-mixin) [class]}}} 
     20 
     21Lets 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: 
     22 
     23'':slider-indicator'' -- sets the shape of the slider indicator, one of :right, :left, :up, :down, :none 
     24 
     25'':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. 
     26 
     27{{{(slider-indicator slider-view) [method]}}} 
     28 
     29Returns 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. 
     30 
     31{{{(slider-tick-marks slider-view) [method]}}} 
     32 
     33Returns the number of tick marks in slider-view, on ''nil'' if the slider doesn't have tick marks. 
     34 
     35== Scroll Bar view == 
     36 
     37{{{scroll-bar-view (subview view-orientation-mixin view-range-mixin view-mouse-tracker-mixin) [class]}}} 
     38 
     39Scroll 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: 
     40 
     41'':scroll-bar-scroller-size'' -- initializes the scroller size, see set-scroll-bar-scroller-size. 
     42 
     43{{{(set-scroll-bar-scroller-size scroll-bar-view size) [method]}}} 
     44 
     45Sets 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. 
     46 
     47{{{(scroll-bar-scroller-size scroll-bar-view) [method]}}} 
     48 
     49Returns the size of the currently visible part of the document, expressed in terms of the same units as used for minimim and maximum. 
     50 
     51== Text Input view == 
     52 
     53{{{text-input-view (subview view-text-mixin) [class]}}} 
     54 
     55Lets the user enter text. Additional initargs: 
     56 
     57'':text-input-locked'' -- initializes the text locked state, see lock-text-input 
     58 
     59'':text-input-multi-line-p'' -- if true, allows multi-line input. 
     60 
     61'':text-input-selection-start'' -- initializes the current selection start offset, see set-text-input-selection 
     62 
     63'':text-input-selection-end'' -- initializes the current selection end offset, see set-text-input-selection 
     64 
     65''TODO: validation'' 
     66 
     67{{{(lock-text-input editable-text-view) [method]}}} 
     68 
     69Locks the text in the view so it can't be modified (even though it's still shown as enabled). 
     70 
     71{{{(unlock-text-input editable-text-view) [method]}}} 
     72 
     73Unlocks the text in the view so it can be modified again. 
     74 
     75{{{(text-input-locked-p editable-text-view) [method]}}} 
     76 
     77True if text in view is locked. 
     78 
     79{{{(text-input-multi-line-p editable-text-view) [method]}}} 
     80 
     81True if multi-line input is supported. 
     82 
     83{{{(text-input-selection editable-text-view) [method]}}} 
     84 
     85Returns two values, the start and end offset of the selection in the text. 
     86 
     87{{{(text-input-selection-start editable-text-view) [method]}}} 
     88 
     89Returns the start offset of the selection. 
     90 
     91{{{(text-input-selection-end editable-text-view) [method]}}} 
     92 
     93Returns the end offset of the selection 
     94 
     95{{{(set-text-input-selection editable-text-view &key start end)}}} 
     96 
     97Sets the selection to the range specified. 
     98 
     99== Password Text Input view == 
     100 
     101{{{password-input-view (text-input-view) [class]}}} 
     102 
     103Subclass of text-input-view for entering passwords. Echos typein as bullets. 
     104 
     105== Static Text view == 
     106 
     107{{{static-text-view (subview view-text-mixin) [class]}}} 
     108 
     109Displays text. Additional initargs: 
     110 
     111'':static-text-truncation'' -- initializes text truncation style, see set-static-text-truncation. 
     112 
     113{{{(set-static-text-truncation static-text-view truncation) [method]}}} 
     114 
     115Sets 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. 
     116 
     117{{{(static-text-truncation static-text-view) [method]}}} 
     118 
     119Returns the truncation style of static-text-view, one of :end, :middle or ''nil''. 
     120 
     121== List Box view == 
     122 
     123{{{list-box-view (subview) [abstract class]}}} 
     124 
     125This 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: 
     126 
     127'':list-box-dimensions'' -- initializes the dimensions, see set-list-box-dimensions. 
     128 
     129'':list-box-selection-type'' -- the type of selection handling to use, one of :single, :contiguous, or :disjoint. 
     130 
     131'':list-box-horizontal-scroll-p'' -- determines whether to have a horizontal scroll bar 
     132 
     133'':list-box-vertical-scroll-p'' -- determines whether to have a vertical scroll bar. 
     134 
     135'':list-box-cell-size'' -- initializes cell seize, see set-list-box-cell-size. 
     136 
     137'':list-box-cell-width'' -- width of each cell, overrides list-box-cell-size 
     138 
     139'':list-box-cell-height'' -- height of each cell, overrides list-box-cell-size 
     140 
     141'':list-box-grow-space-p'' -- true to indicate that the conrol is draw so that there is room for a size box. 
     142 
     143''TODO: font style and key filter '' 
     144 
     145''TODO: MCL also supports per-cell font and color, because it does the drawing itself'' 
     146 
     147 
     148{{{(list-box-cell-text list-box-view cell) [method]}}} 
     149 
     150Returns 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. 
     151 
     152{{{(set-list-box-dimensions list-box-view dimensions) [method]}}} 
     153 
     154Sets the number of columns in list-box-view to (point-h dimensions) and the number of rows to (point-v dimensions). 
     155 
     156{{{(list-box-dimensions list-box-view) [method]}}} 
     157 
     158Returns the dimensions of list-box-view as (point column-count row-count). 
     159 
     160{{{(set-list-box-visible-dimensions list-box-view dimensions) [method]}}} 
     161 
     162Resizes list-box-view so that (point-h dimensions) columns and (point-v dimensions) rows are visible. 
     163 
     164{{{(list-box-visible-dimensions list-box-view) [method]}}} 
     165 
     166Returns the number of cells visible in the horizontal and vertical dimensions. 
     167 
     168{{{(set-list-box-cell-size list-box-view size) [method]}}} 
     169 
     170Sets 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. 
     171 
     172{{{(list-box-cell-size list-box-view) [method]}}} 
     173 
     174Returns the size of a cell in list-box-view. All cells have the same size. 
     175 
     176{{{(list-box-selection-type list-box-view) [method]}}} 
     177 
     178Returns the selection type of list-box-view, one of :single, :contiguous, or :disjoint. 
     179 
     180{{{(list-box-horizontal-scroll-p list-box-view) [method]}}} 
     181 
     182Returns true if list-box-view has a horizontal scroll bar. 
     183 
     184{{{(list-box-vertical-scroll-p list-box-view) [method]}}} 
     185 
     186Returns true if list-box-view has a vertical scroll bar. 
     187 
     188{{{(list-box-scroll-to-cell list-box-view cell) [method]}}} 
     189 
     190Scrolls list-box-view so that the cell in column (point-h cell) and row (point-v cell) is in the upper-left corner. 
     191 
     192{{{(list-box-scroll-position list-box-view) [method]}}} 
     193 
     194Returns the cell in the upper-left corner, represented as a point. 
     195 
     196{{{(list-box-cell-select list-box-view cell) [method]}}} 
     197 
     198Selects the cell in column (point-h cell) and row (point-v cell). 
     199 
     200{{{(list-box-cell-deselect list-box-view cell) [method]}}} 
     201 
     202Deselect the cell in column (point-h cell) and row (point-v cell). 
     203 
     204{{{(list-box-cell-selected-p list-box-view cell) [method]}}} 
     205 
     206True if the cell in column (point-h cell) and row (point-v cell) is selected. 
     207 
     208{{{(list-box-selected-cells list-box-view) [method]}}} 
     209 
     210Returns a list of all currently selected cells in list-box-view. Each cell is represented by a point. 
     211 
     212== Array view == 
     213 
     214{{{array-view (list-box-view) [class]}}} 
     215 
     216A type of list box view that displays the elements of a two dimensional array. Additional initargs: 
     217 
     218'':list-box-array'' -- initializes the view array, see set-list-box-array. 
     219 
     220{{{(set-list-box-array array-view array) [method]}}} 
     221 
     222Sets 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. 
     223 
     224{{{(list-box-array array-view) [method]}}} 
     225 
     226Returns the array displayed in array-view. It should not be directly modified while being used by an array view. 
     227 
     228{{{(list-box-cell-text array-view cell) [method]}}} 
     229 
     230The default array-view method obtains the array element corresponding to ''cell'' and converts it to a string using ''princ-to-string''. 
     231 
     232== Sequence view == 
     233 
     234{{{sequence-view (list-box-view view-orientation-mixin) [class]}}} 
     235 
     236A type of list box view that displays the elements of a sequence, horizontally or vertically. Additional initargs: 
     237 
     238'':list-box-sequence'' -- initializes the view sequence, see set-list-box-sequence. 
     239 
     240{{{(set-list-box-sequence sequence-view sequence) [method]}}} 
     241 
     242Sets 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. 
     243 
     244{{{(list-box-sequence sequence-view) [method]}}} 
     245 
     246Returns the sequence displayed in sequence-view.  It should not be directly modified while being used by a sequence view. 
     247 
     248{{{(list-box-cell-text sequence-view cell) [method]}}} 
     249 
     250The default sequence-view method obtains the sequence element corresponding to ''cell'' and converts it to a string using ''princ-to-string''. 
     251 
     252== Push Button view == 
     253 
     254{{{push-button-view (subview view-text-mixin view-action-mixin) [class]}}} 
     255 
     256Push buttons are rounded rectangles that display the view-text, and when pressed invoke the view-action. Additional initargs: 
     257 
     258'':default-button-p'' -- if true, this is the default button. Default buttons are drawn with an outline and may be activated by hitting Return. 
     259 
     260'':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. 
     261 
     262{{{(default-button-p push-button-view) [method]}}} 
     263 
     264True if this is the default button. 
     265 
     266{{{(cancel-button-p push-button-view) [method]}}} 
     267 
     268True if this is the cancel button. 
     269 
     270''TODO: push buttons with icons -- would need support for icons…'' 
     271 
     272== Radio Button view == 
     273 
     274{{{radio-button-view (subview view-text-mixin view-state-mixin) [class]}}} 
     275 
     276Radio 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. 
     277 
     278{{{(view-valid-states radio-button-view) [method]}}} 
     279 
     280Returns ''%%'%%(:on :off :mixed)''. 
     281 
     282== Radio Button Group view == 
     283 
     284{{{radio-button-group-view (subview) [class]}}} 
     285 
     286An 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. 
     287 
     288{{{(selected-group-radio-button radio-button-group-view) [method]}}} 
     289 
     290Returns the currently selected radio button in the group. 
     291 
     292== Checkbox view == 
     293 
     294{{{checkbox-view (subview view-text-mixin view-state-mixin) [class]}}} 
     295 
     296Checkboxes 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. 
     297 
     298{{{(view-valid-states checkbox-view) [method]}}} 
     299 
     300Returns ''%%'%%(:on :off :mixed)''. 
     301 
     302== Data Browser view == 
     303 
     304databrowser-view (...) [class] 
     305 
     306''TODO: tbd'' 
     307 
     308== Pop-up Benus == 
     309 
     310''TODO: tbd'' 
     311 
     312== Custom view == 
     313 
     314{{{custom-view (subview) [class]}}} 
     315 
     316Custom views allow you to implement the view's appearance and behavior. Initiargs: 
     317 
     318'':view-mouse-down-handler'' -- initializes the mouse-down handler, see set-view-mouse-down-handler. 
     319 
     320'':view-mouse-up-handler'' -- initializes the mouse-up handler, see set-view-mouse-up-handler. 
     321 
     322'':view-key-handler'' -- initializes the keyboard input handler, see set-view-key-handler. 
     323 
     324'':view-draw-handler'' -- initializes the handler for drawing the view, see set-view-draw-handler. 
     325 
     326{{{(set-view-mouse-down-handler custom-view handler) [method]}}} 
     327 
     328Sets 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. 
     329 
     330{{{(view-mouse-down-handler custom-view) [method]}}} 
     331 
     332Returns the view's mouse-down handler. 
     333 
     334{{{(set-view-mouse-up-handler custom-view handler) [method]}}} 
     335 
     336Sets 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. 
     337 
     338{{{(view-mouse-up-handler custom-view) [method]}}} 
     339 
     340Returns the view's mouse-up handler. 
     341 
     342{{{(set-view-key-handler custom-view handler) [method]}}} 
     343 
     344Sets 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.'' 
     345 
     346{{{(view-key-handler custom-view) [method]}}} 
     347 
     348Returns the view's key handler. 
     349 
     350{{{(set-view-draw-handler custom-view handler) [method]}}} 
     351 
     352Sets 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. 
     353 
     354{{{(view-draw-handler custom-view) [method]}}} 
     355 
     356Returns the view's draw handler. 
     357 
     358 
     359''TODO: Need to provide utility fns for switching focus so custom views can respond to tab/enter.'' 
     360 
     361''TODO: Need to provide protocol for extending view-action-mixin so can do custom controls'' 
     362