include/X11/Xmu/EditresP.h

   1 /*
   2
   3 Copyright 1989, 1998  The Open Group
   4
   5 Permission to use, copy, modify, distribute, and sell this software and its
   6 documentation for any purpose is hereby granted without fee, provided that
   7 the above copyright notice appear in all copies and that both that
   8 copyright notice and this permission notice appear in supporting
   9 documentation.
  10
  11 The above copyright notice and this permission notice shall be included in
  12 all copies or substantial portions of the Software.
  13
  14 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
  17 OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  18 AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  19 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  20
  21 Except as contained in this notice, the name of The Open Group shall not be
  22 used in advertising or otherwise to promote the sale, use or other dealings
  23 in this Software without prior written authorization from The Open Group.
  24
  25 */
  26
  27 /*
  28  * Author:  Chris D. Peterson, MIT X Consortium
  29  */
  30
  31 /************************************************************
  32
  33                 The Editres Protocol
  34
  35
  36   The Client message sent to the application is:
  37
  38   ATOM = "ResEditor"            --- RES_EDITOR_NAME
  39
  40   FORMAT = 32                   --- RES_EDIT_SEND_EVENT_FORMAT
  41
  42   l[0] = timestamp
  43   l[1] = command atom name
  44   l[2] = ident of command
  45   l[3] = protocol version number to use
  46
  47
  48
  49   The binary protocol has the following format:
  50
  51         Card8:          8-bit unsingned integer
  52         Card16:         16-bit unsingned integer
  53         Card32:         32-bit unsingned integer
  54         Int16:          16-bit signed integer
  55         Window:         32-bit value
  56         Widget:         32-bit value
  57         String8:        ListOfCard8
  58
  59         [a][b][c] represent an exclusive list of choices.
  60
  61         All widgets are passed as a list of widgets, containing the
  62         full instance heirarch of this widget.  The hierarchy is ordered
  63         from parent to child.  Thus the first element of each list is
  64         the root of the widget tree (this makes verifying that the widget
  65         still exists, MUCH faster).
  66
  67         ListOfFoo comprises a list of things in the following format:
  68
  69         number:                 Card16
  70         <number> things:        ????
  71
  72   This is a synchronous protocol, every request MUST be followed by a
  73   reply.
  74
  75   Request:
  76
  77         Serial Number:  Card8
  78         Op Code:        Card8 - { SendWidgetTree = 0,
  79                                   SetValues = 1,
  80                                   GetResources = 2,
  81                                   GetGeometry = 3,
  82                                   FindChild = 4,
  83                                   GetValues = 5 }
  84         Length:         Card32
  85         Data:
  86
  87    Reply:
  88
  89         Serial Number:  Card8
  90         Type:           Card8 - { Formatted = 0,
  91                                   Unformatted = 1,
  92                                   ProtocolMismatch = 2
  93                                 }
  94         Length:         Card32
  95
  96
  97    Byte Order:
  98
  99         All Fields are MSB -> LSB
 100
 101     Data:
 102
 103         Formatted:
 104
 105                 The data contains the reply information for the request as
 106                 specified below if the reply type is "Formatted".  The return
 107                 values for the other reply types are shown below.
 108
 109         Unformatted:
 110
 111                 Message:        String8
 112
 113         ProtocolMismatch:
 114
 115                 RequestedVersion:       Card8
 116
 117 ------------------------------------------------------------
 118
 119    SendWidgetTree:
 120
 121         --->
 122
 123         Number of Entries:      Card16
 124         Entry:
 125                 widget:         ListOfWidgets
 126                 name:           String8
 127                 class:          String8
 128                 window:         Card32
 129                 toolkit:        String8
 130
 131         Send Widget Tree returns the toolkit type, and a fuly specified list
 132         of widgets for each widget in the tree.  This is enough information
 133         to completely reconstruct the entire widget heirarchy.
 134
 135         The window return value contains the Xid of the window currently
 136         used by this widget.  If the widget is unrealized then 0 is returned,
 137         and if widget is a non-windowed object a value of 2 is returned.
 138
 139    SetValues:
 140
 141         name:   String8
 142         type:   String8
 143         value:  String8
 144         Number of Entries:      Card16
 145         Entry:
 146                 widget:         ListOfWidgets
 147
 148         --->
 149
 150         Number of Entries:      Card16
 151         Entry:
 152                 widget:         ListOfWidgets
 153                 message:        String8
 154
 155         SetValues will allow the same resource to be set on a number of
 156         widgets.  This function will return an error message if the SetValues
 157         request caused an Xt error.
 158
 159   GetValues:
 160
 161         names:                ListOfString8
 162         widget:               Widget
 163
 164         --->
 165         novalues:             ListOfCard16
 166         values:               ListOfString8
 167
 168         GetValues will allow a number of resource values to be read
 169         on a particular widget.  The request specifies the names of
 170         the resources wanted and the widget id these resources are
 171         from.  The reply returns a list of indices from the requests
 172         name list of resources for which a value can not be returned.
 173         It also returns a list of returned values, in the order of the
 174         requests names list, skipping those indices present in novalues.
 175
 176    GetResources:
 177
 178         Number of Entries:      Card16
 179         Entry
 180                 widget:         ListOfWidgets:
 181
 182         ---->
 183
 184         Number of Entries:      Card16
 185         Entry
 186                 Widget:                 ListOfWidgets:
 187                 Error:                  Bool
 188
 189                 [ Message:              String 8 ]
 190                 [ Number of Resources:  Card16
 191                 Resource:
 192                         Kind:   {normal, constraint}
 193                         Name:   String8
 194                         Class:  String8
 195                         Type:   String8 ]
 196
 197         GetResource retrieves the kind, name, class and type for every
 198         widget passed to it.  If an error occured with the resource fetch
 199         Error will be set to True for the given widget and a message
 200         is returned rather than the resource info.
 201
 202   GetGeometry:
 203
 204         Number of Entries:      Card16
 205         Entry
 206                 Widget:         ListOfWidgets:
 207
 208         ---->
 209
 210         Number of Entries:      Card16
 211         Entry
 212                 Widget:                 ListOfWidgets:
 213                 Error:                  Bool
 214
 215                 [ message:              String 8 ]
 216                 [ mapped:       Boolean
 217                   X:            Int16
 218                   Y:            Int16
 219                   Width:        Card16
 220                   Height:       Card16
 221                   BorderWidth:  Card16 ]
 222
 223         GetGeometry retreives the mapping state, x, y, width, height
 224         and border width for each widget specified.  If an error occured
 225         with the geometry fetch "Error" will be set to True for the given
 226         widget and a message is returned rather than the geometry info.
 227         X an Y corrospond to the root coordinates of the upper left corner
 228         of the widget (outside the window border).
 229
 230   FindChild:
 231
 232         Widget:         ListOfWidgets
 233         X:              Int16
 234         Y:              Int16
 235
 236         --->
 237
 238         Widget:         ListOfWidgets
 239
 240         Find Child returns a descendent of the widget specified that
 241         is at the root coordinates specified.
 242
 243         NOTE:
 244
 245         The returned widget is undefined if the point is contained in
 246         two or more mapped widgets, or in two overlapping Rect objs.
 247
 248   GetValues:
 249
 250         names:                ListOfString8
 251         widget:               Widget
 252
 253         --->
 254
 255         values:               ListOfString8
 256
 257         GetValues will allow a number of resource values to be read
 258         on a particular widget.  Currently only InterViews 3.0.1 Styles
 259         and their attributes are supported.  In addition, the current
 260         user interface  only supports the return of 1 resource.  The ability
 261         to specify and return multiple resources is defined for future editres
 262         interfaces where some or all of a widgets resource values are returned
 263         and displayed at once.
 264
 265
 266 ************************************************************/
 267
 268 #include <X11/Intrinsic.h>
 269 #include <X11/Xfuncproto.h>
 270
 271 #define XER_NBBY 8              /* number of bits in a byte */
 272 #define BYTE_MASK 255
 273
 274 #define HEADER_SIZE 6
 275
 276 #define EDITRES_IS_OBJECT 2
 277 #define EDITRES_IS_UNREALIZED 0
 278
 279 /*
 280  * Format for atoms
 281  */
 282 #define EDITRES_FORMAT             8
 283 #define EDITRES_SEND_EVENT_FORMAT 32
 284
 285 /*
 286  * Atoms
 287  */
 288 #define EDITRES_NAME         "Editres"
 289 #define EDITRES_COMMAND_ATOM "EditresCommand"
 290 #define EDITRES_COMM_ATOM    "EditresComm"
 291 #define EDITRES_CLIENT_VALUE "EditresClientVal"
 292 #define EDITRES_PROTOCOL_ATOM "EditresProtocol"
 293
 294 typedef enum {
 295   SendWidgetTree = 0,
 296                SetValues      = 1,
 297                GetResources   = 2,
 298                GetGeometry    = 3,
 299                FindChild      = 4,
 300                GetValues      = 5
 301 } EditresCommand;
 302
 303 typedef enum {
 304   NormalResource     = 0,
 305   ConstraintResource = 1
 306 } ResourceType;
 307
 308 /*
 309  * The type of a resource identifier
 310  */
 311 typedef unsigned char ResIdent;
 312
 313 typedef enum {
 314   PartialSuccess   = 0,
 315   Failure          = 1,
 316   ProtocolMismatch = 2
 317 } EditResError;
 318
 319 typedef struct _WidgetInfo {
 320     unsigned short num_widgets;
 321   unsigned long *ids;
 322     Widget real_widget;
 323 } WidgetInfo;
 324
 325 typedef struct _ProtocolStream {
 326     unsigned long size, alloc;
 327     unsigned char *real_top, *top, *current;
 328 } ProtocolStream;
 329
 330 /************************************************************
 331  * Function definitions for reading and writing protocol requests
 332  ************************************************************/
 333 _XFUNCPROTOBEGIN
 334
 335 void _XEditResPutString8
 336 (
 337  ProtocolStream         *stream,
 338  _Xconst char           *str
 339  );
 340
 341 void _XEditResPut8
 342 (
 343  ProtocolStream         *stream,
 344  unsigned int           value
 345  );
 346
 347 void _XEditResPut16
 348 (
 349  ProtocolStream         *stream,
 350  unsigned int           value
 351  );
 352
 353 void _XEditResPut32
 354 (
 355  ProtocolStream         *stream,
 356  unsigned long          value
 357  );
 358
 359 void _XEditResPutWidgetInfo
 360 (
 361  ProtocolStream         *stream,
 362  WidgetInfo             *info
 363  );
 364
 365 void _XEditResResetStream
 366 (
 367  ProtocolStream         *stream
 368  );
 369
 370 Bool _XEditResGet8
 371 (
 372  ProtocolStream         *stream,
 373  unsigned char          *value
 374  );
 375
 376 Bool _XEditResGet16
 377 (
 378  ProtocolStream         *stream,
 379  unsigned short         *value
 380  );
 381
 382 Bool _XEditResGetSigned16
 383 (
 384  ProtocolStream         *stream,
 385  short                  *value
 386  );
 387
 388 Bool _XEditResGet32
 389 (
 390  ProtocolStream         *stream,
 391  unsigned long          *value
 392  );
 393
 394 Bool _XEditResGetString8
 395 (
 396  ProtocolStream         *stream,
 397  char                   **str
 398  );
 399
 400 Bool _XEditResGetWidgetInfo
 401 (
 402  ProtocolStream         *stream,
 403  WidgetInfo             *info
 404  );
 405
 406 _XFUNCPROTOEND