DOC/Calls

   1
   2  This file list some the calls that are recognised by various panes.
   3
   4 # Misc
   5
   6 ## view:changed
   7
   8 This is sent to a focus pane when a change happens that will affect
   9 this particular view of a document.  This is often a change in highlights,
  10 such as a selection.
  11
  12 If both mark and mark2 are given, the change reported is only between
  13 the marks.  If neither mark is given, the entire view is suspect.
  14 If only one mark is given, then the change is small and either starts
  15 at 'mark' or ends at 'mark2'.  'num' gives the length in characters,
  16 but if this length extends to another line, it may not be honoured.
  17
  18
  19 # Documents
  20
  21 ## doc:request:FOO
  22
  23 Request that when the document sends notification "FOO", it gets sent
  24 to the provided focus.
  25
  26 ## doc:notify:FOO
  27
  28 Request that the document sends notification FOO.
  29
  30 # Editor
  31
  32 ## editor:request:FOO
  33
  34 Request to received notification for FOO send on the editor.
  35
  36 ## editor:notify:FOO
  37
  38 Send notification "FOO" from the editor.
  39
  40 Known notifications include:
  41
  42 - all-displays.  This is sent to all displays.  The callback will
  43   contain a timestamp for the most recent event in 'num'.  The number
  44   of times the callback is called indicates how many displays there are.
  45
  46
  47 # Window/input
  48
  49 ## Window:request:FOO
  50
  51 Ask to receive notification "FOO" send to current window.
  52
  53 ## Window:notify:FOO
  54
  55 Send notification "FOO" to current window.
  56
  57 Known notifications include:
  58
  59 - Keystroke-notify - string is the key name
  60 - Mouse-event-notify - string is the event name
  61
  62 # Displays
  63
  64 A display pane provides linkage to keyboard/pointer input, and visual output.
  65 It will generate Keystroke and Mouse-event events for its parent, and expect
  66 various Draw: event from children.
  67
  68 A display pane should register against the root, and will typically be
  69 re-parented over an "input handler" pane, and have a stack of other
  70 panes on top.  If the display supports scaling, it should set an
  71 attributes "scale:M" with value "WxH" where "W" is pixel-width of 'M' in
  72 default font, and "H" is pixel-height of a line.
  73
  74 ## Draw:clear
  75
  76 Draw:clear will allocate a display image for the focus pane and clear
  77 it.  "str1" can be attributes for the background, typically a background
  78 colour such as "bg:cyan".  If no attributes are given and there is
  79 another pane closer to the root which has been cleared, the appropriate
  80 section of the image for that pane is copied it the image for 'focus'.
  81 If ther is no image to copy from, the pane is cleared to "bg:white".
  82
  83 ## Draw:text
  84
  85 This requests that text be drawn on the display.  If text already exists
  86 at the same location it may be replaced or it may be blended.
  87
  88 - str1 is the text to draw.  Control characters should be avoided.
  89 - (x,y) gives the position for the top-left corner of the text
  90 - str2 is attributes to apply to the text
  91 - num, if non-negative, is a byte offset in str1 where a cursor should
  92   be placed.  The character following str1+num will be highlighted to
  93   indicate that presence of the cursor before it.  If num is the length
  94   of str1, then a cursor-on-space will appear after the drawn text.
  95 - num2 is a scale to apply to the text.  1000 is the default (used if
  96   num2==0)  It is roughly "pixels per point * 1000"
  97
  98 ## Draw:text-size
  99
 100 This request measures the size of 'str1'.  The result is returned using
 101 comm2 as the (x,y) pair.
 102
 103 - str1 is the string to measure
 104 - str2 is the attributes
 105 - num, if non-negative, is a pixel offset to the right of the left edge
 106   The byte-position in the resulting image which would be drawn at the
 107   offset is reported
 108 - num2 is a scale, as with Draw:text
 109 - comm2 is called with the results of the measurement:
 110     - num is the byte offset corresponding to the requested pixel offset
 111     - num2 is the "ascent" for the text - pixel distance from baseline
 112       to top. This is typically used to determine where the "Top" left
 113       of the image should go when calling Draw:text
 114     - (x,y) is the width and height of the drawing of the text.
 115
 116 ## Draw:image
 117
 118 Draw an image on the pane (or ancestor which as been cleared).
 119
 120 - str1 identifies the images, either "file:FILENAME" or "comm:COMMAND".
 121   If "comm:" the command is run and result should be returned as 'bytes'
 122   (comm2 called with ->str1 as array of bytes, ->num1 as length).
 123 - str2 contains 'mode' information.
 124       - By default the image is placed centrally in the pane
 125         and scaled to use either fully height or fully width.
 126       - Various letters modify this:
 127             'S' - stretch to use full height *and* full width
 128             'L' - place on left if full width isn't used
 129             'R' - place on right if full width isn't used
 130             'T' - place at top if full height isn't used
 131             'B' - place at bottom if full height isn't used.
 132         Also a suffix ":NNxNN" will be parse and the two numbers used
 133         to give number of rows and cols to overlay on the image for
 134         the purpose of cursor positioning.  If these are present and
 135         p->cx,cy are not negative, draw a cursor at p->cx,cy highlighting
 136         the relevant cell.
 137 - num, num2 if both positive, give width and height to scale to,
 138        over-riding the default scaling.
 139        If only num is positive, then it is a scale factor *1024
 140        to be applied to the image.
 141 - x,y give a top-left pixel in the scaled image to display.  Only
 142       this pixel and those to right and below might be shown.
 143       Negative values allow a margin between pane edge and this image.
 144
 145 ## all-displays
 146
 147 Display should request notifications of "all-displays" from the editor
 148 ("editor:request:all-displays").  When a notification comes it should
 149 reply (via comm2) with num1 being the time in seconds of the last
 150 interaction with the user.  This allows the "most recently active"
 151 display to be deteremined.
 152
 153 When a close request is sent to the display, it should call
 154 "editor:notify:all-displays" and if the num of reply is 1 (presumably
 155 from this display), it should generally refuse, as closing the last
 156 display can be awkward.
 157
 158 ## Window:close
 159
 160 This is a request for the display to close - may be rejected if it is
 161 the only display left.
 162
 163 ## Window:set:ATTR
 164
 165 Set any attribute on the display pane.
 166
 167 The attribute "no-close" affects closing.  If a Window:close request
 168 arrives when "no-close" attribute is a non-empty string, that string
 169 should be reported via a message, and the close should be rejected.
 170
 171 ## Window:external-viewer
 172
 173 str1 is a filename and str2 is (optionally) a basename template
 174 containing "XXXXXX".  An external viewer (typically xdg-open) should be
 175 run on the file.  If the display is on a different host to where the
 176 file is stored, some action might be taken to copy it and provide a
 177 local names, based on str2.
 178
 179 ## Window:fullscreen
 180
 181 If num1 > 0, display should switch to full-screen mode if possible.
 182 If num1 <= 0, display should switch away from full-screen mode.
 183
 184 ## Window:new
 185
 186 If it is possible to duplicate the display (e.g.  similar window on same
 187 output), do that.
 188