Version 5.4.3.2, tag libreoffice-5.4.3.2
[LibreOffice.git] / include / LibreOfficeKit / LibreOfficeKitEnums.h
blob300b71bb01ff46003b014d1e459dfee18786480e
1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
5 * This Source Code Form is subject to the terms of the Mozilla Public
6 * License, v. 2.0. If a copy of the MPL was not distributed with this
7 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
8 */
10 #ifndef INCLUDED_LIBREOFFICEKIT_LIBREOFFICEKITENUMS_H
11 #define INCLUDED_LIBREOFFICEKIT_LIBREOFFICEKITENUMS_H
13 #ifdef __cplusplus
14 extern "C"
16 #endif
18 #if defined LOK_USE_UNSTABLE_API || defined LIBO_INTERNAL_ONLY
19 typedef enum
21 LOK_DOCTYPE_TEXT,
22 LOK_DOCTYPE_SPREADSHEET,
23 LOK_DOCTYPE_PRESENTATION,
24 LOK_DOCTYPE_DRAWING,
25 LOK_DOCTYPE_OTHER
27 LibreOfficeKitDocumentType;
29 typedef enum
31 LOK_PARTMODE_SLIDES,
32 LOK_PARTMODE_NOTES
34 LibreOfficeKitPartMode;
36 typedef enum
38 LOK_TILEMODE_RGBA,
39 LOK_TILEMODE_BGRA
41 LibreOfficeKitTileMode;
43 /** Optional features of LibreOfficeKit, in particular callbacks that block
44 * LibreOfficeKit until the corresponding reply is received, which would
45 * deadlock if the client does not support the feature.
47 * @see lok::Office::setOptionalFeatures().
49 typedef enum
51 /**
52 * Handle LOK_CALLBACK_DOCUMENT_PASSWORD by prompting the user
53 * for a password.
55 * @see lok::Office::setDocumentPassword().
57 LOK_FEATURE_DOCUMENT_PASSWORD = (1ULL << 0),
59 /**
60 * Handle LOK_CALLBACK_DOCUMENT_PASSWORD_TO_MODIFY by prompting the user
61 * for a password.
63 * @see lok::Office::setDocumentPassword().
65 LOK_FEATURE_DOCUMENT_PASSWORD_TO_MODIFY = (1ULL << 1),
67 /**
68 * Request to have the part number as an 5th value in the
69 * LOK_CALLBACK_INVALIDATE_TILES payload.
71 LOK_FEATURE_PART_IN_INVALIDATION_CALLBACK = (1ULL << 2),
73 /**
74 * Turn off tile rendering for annotations
76 LOK_FEATURE_NO_TILED_ANNOTATIONS = (1ULL << 3)
78 LibreOfficeKitOptionalFeatures;
80 // This enumerates the types of callbacks emitted to a LibreOfficeKit
81 // object's callback function or to a LibreOfficeKitDocument object's
82 // callback function. No callback type will be emitted to both. It is a
83 // bit unfortunate that the same enum contains both kinds of
84 // callbacks.
86 // TODO: We should really add some indication at the documentation for
87 // each enum value telling which type of callback it is.
89 typedef enum
91 /**
92 * Any tiles which are over the rectangle described in the payload are no
93 * longer valid.
95 * Rectangle format: "x, y, width, height", where all numbers are document
96 * coordinates, in twips. When all tiles are supposed to be dropped, the
97 * format is the "EMPTY" string.
99 * @see LOK_FEATURE_PART_IN_INVALIDATION_CALLBACK.
101 LOK_CALLBACK_INVALIDATE_TILES = 0,
103 * The size and/or the position of the visible cursor changed.
105 * Rectangle format is the same as LOK_CALLBACK_INVALIDATE_TILES.
107 LOK_CALLBACK_INVALIDATE_VISIBLE_CURSOR = 1,
109 * The list of rectangles representing the current text selection changed.
111 * List format is "rectangle1[; rectangle2[; ...]]" (without quotes and
112 * brackets), where rectangleN has the same format as
113 * LOK_CALLBACK_INVALIDATE_TILES. When there is no selection, an empty
114 * string is provided.
116 LOK_CALLBACK_TEXT_SELECTION = 2,
118 * The position and size of the cursor rectangle at the text
119 * selection start. It is used to draw the selection handles.
121 * This callback must be called prior to LOK_CALLBACK_TEXT_SELECTION every
122 * time the selection is updated.
124 * Rectangle format is the same as LOK_CALLBACK_INVALIDATE_TILES.
126 LOK_CALLBACK_TEXT_SELECTION_START = 3,
128 * The position and size of the cursor rectangle at the text
129 * selection end. It is used to draw the selection handles.
131 * This callback must be called prior to LOK_CALLBACK_TEXT_SELECTION every
132 * time the selection is updated.
134 * Rectangle format is the same as LOK_CALLBACK_INVALIDATE_TILES.
136 LOK_CALLBACK_TEXT_SELECTION_END = 4,
138 * The blinking text cursor is now visible or not.
140 * Clients should assume that this is true initially and are expected to
141 * hide the blinking cursor at the rectangle described by
142 * LOK_CALLBACK_INVALIDATE_VISIBLE_CURSOR once it becomes false. Payload is
143 * either the "true" or the "false" string.
145 LOK_CALLBACK_CURSOR_VISIBLE = 5,
147 * The size and/or the position of the graphic selection changed.
149 * Rectangle format is the same as LOK_CALLBACK_INVALIDATE_TILES.
151 LOK_CALLBACK_GRAPHIC_SELECTION = 6,
154 * User clicked on an hyperlink that should be handled by other
155 * applications accordingly.
157 LOK_CALLBACK_HYPERLINK_CLICKED = 7,
160 * Emit state update to the client.
161 * For example, when cursor is on bold text, this callback is triggered
162 * with payload: ".uno:Bold=true"
164 LOK_CALLBACK_STATE_CHANGED = 8,
167 * Start a "status indicator" (here restricted to a progress bar type
168 * indicator). The payload is the descriptive text (or empty). Even if
169 * there is no documentation that would promise so, we assume that de facto
170 * for a document being viewed or edited, there will be at most one status
171 * indicator, and its descriptive text will not change.
173 * Note that for the case of the progress indication during loading of a
174 * document, the status indicator callbacks will arrive to the callback
175 * registered for the LibreOfficeKit (singleton) object, not a
176 * LibreOfficeKitDocument one, because we are in the very progress of
177 * loading a document and then constructing a LibreOfficeKitDocument
178 * object.
180 LOK_CALLBACK_STATUS_INDICATOR_START = 9,
183 * Sets the numeric value of the status indicator.
184 * The payload should be a percentage, an integer between 0 and 100.
186 LOK_CALLBACK_STATUS_INDICATOR_SET_VALUE = 10,
189 * Ends the status indicator.
191 * Not necessarily ever emitted.
193 LOK_CALLBACK_STATUS_INDICATOR_FINISH = 11,
196 * No match was found for the search input
198 LOK_CALLBACK_SEARCH_NOT_FOUND = 12,
201 * Size of the document changed.
203 * Payload format is "width, height", i.e. clients get the new size without
204 * having to do an explicit lok::Document::getDocumentSize() call.
206 LOK_CALLBACK_DOCUMENT_SIZE_CHANGED = 13,
209 * The current part number is changed.
211 * Payload is a single 0-based integer.
213 LOK_CALLBACK_SET_PART = 14,
216 * Selection rectangles of the search result when find all is performed.
218 * Payload format example, in case of two matches:
221 * "searchString": "...",
222 * "highlightAll": true|false, // this is a result of 'search all'
223 * "searchResultSelection": [
225 * "part": "...",
226 * "rectangles": "..."
227 * },
229 * "part": "...",
230 * "rectangles": "..."
235 * - searchString is the search query
236 * - searchResultSelection is an array of part-number and rectangle list
237 * pairs, in LOK_CALLBACK_SET_PART / LOK_CALLBACK_TEXT_SELECTION format.
239 LOK_CALLBACK_SEARCH_RESULT_SELECTION = 15,
242 * Result of the UNO command execution when bNotifyWhenFinished was set
243 * to 'true' during the postUnoCommand() call.
245 * The result returns a success / failure state, and potentially
246 * additional data:
249 * "commandName": "...", // the command for which this is the result
250 * "success": true/false, // when the result is "don't know", this is missing
251 * // TODO "result": "..." // UNO Any converted to JSON (not implemented yet)
254 LOK_CALLBACK_UNO_COMMAND_RESULT = 16,
257 * The size and/or the position of the cell cursor changed.
259 * Rectangle format is the same as LOK_CALLBACK_INVALIDATE_TILES.
261 LOK_CALLBACK_CELL_CURSOR = 17,
264 * The current mouse pointer style.
266 * Payload is a css mouse pointer style.
268 LOK_CALLBACK_MOUSE_POINTER = 18,
271 * The text content of the formula bar in Calc.
273 LOK_CALLBACK_CELL_FORMULA = 19,
276 * Loading a document requires a password.
278 * Loading the document is blocked until the password is provided via
279 * lok::Office::setDocumentPassword(). The document cannot be loaded
280 * without the password.
282 LOK_CALLBACK_DOCUMENT_PASSWORD = 20,
285 * Editing a document requires a password.
287 * Loading the document is blocked until the password is provided via
288 * lok::Office::setDocumentPassword().
290 LOK_CALLBACK_DOCUMENT_PASSWORD_TO_MODIFY = 21,
293 * An error happened.
295 * The payload returns information further identifying the error, like:
298 * "classification": "error" | "warning" | "info"
299 * "kind": "network" etc.
300 * "code": a structured 32-bit error code, the ErrCode from LibreOffice's <tools/errcode.hxx>
301 * "message": freeform description
304 LOK_CALLBACK_ERROR = 22,
307 * Context menu structure
309 * Returns the structure of context menu. Contains all the separators &
310 * submenus, example of the returned structure:
313 * "menu": [
314 * { "text": "label text1", "type": "command", "command": ".uno:Something1", "enabled": "true" },
315 * { "text": "label text2", "type": "command", "command": ".uno:Something2", "enabled": "false" },
316 * { "type": "separator" },
317 * { "text": "label text2", "type": "menu", "menu": [ { ... }, { ... }, ... ] },
318 * ...
322 * The 'command' can additionally have a checkable status, like:
324 * {"text": "label text3", "type": "command", "command": ".uno:Something3", "checktype": "checkmark|radio|auto", "checked": "true|false"}
326 LOK_CALLBACK_CONTEXT_MENU = 23,
329 * The size and/or the position of the view cursor changed. A view cursor
330 * is a cursor of an other view, the current view can't change it.
332 * The payload format:
335 * "viewId": "..."
336 * "rectangle": "..."
339 * - viewId is a value returned earlier by lok::Document::createView()
340 * - rectangle uses the format of LOK_CALLBACK_INVALIDATE_VISIBLE_CURSOR
342 LOK_CALLBACK_INVALIDATE_VIEW_CURSOR = 24,
345 * The text selection in one of the other views has changed.
347 * The payload format:
350 * "viewId": "..."
351 * "selection": "..."
354 * - viewId is a value returned earlier by lok::Document::createView()
355 * - selection uses the format of LOK_CALLBACK_TEXT_SELECTION.
357 LOK_CALLBACK_TEXT_VIEW_SELECTION = 25,
360 * The cell cursor in one of the other views has changed.
362 * The payload format:
365 * "viewId": "..."
366 * "rectangle": "..."
369 * - viewId is a value returned earlier by lok::Document::createView()
370 * - rectangle uses the format of LOK_CALLBACK_CELL_CURSOR.
372 LOK_CALLBACK_CELL_VIEW_CURSOR = 26,
375 * The size and/or the position of a graphic selection in one of the other
376 * views has changed.
378 * The payload format:
381 * "viewId": "..."
382 * "selection": "..."
385 * - viewId is a value returned earlier by lok::Document::createView()
386 * - selection uses the format of LOK_CALLBACK_INVALIDATE_TILES.
388 LOK_CALLBACK_GRAPHIC_VIEW_SELECTION = 27,
391 * The blinking text cursor in one of the other views is now visible or
392 * not.
394 * The payload format:
397 * "viewId": "..."
398 * "visible": "..."
401 * - viewId is a value returned earlier by lok::Document::createView()
402 * - visible uses the format of LOK_CALLBACK_CURSOR_VISIBLE.
404 LOK_CALLBACK_VIEW_CURSOR_VISIBLE = 28,
407 * The size and/or the position of a lock rectangle in one of the other
408 * views has changed.
410 * The payload format:
413 * "viewId": "..."
414 * "rectangle": "..."
417 * - viewId is a value returned earlier by lok::Document::createView()
418 * - rectangle uses the format of LOK_CALLBACK_INVALIDATE_TILES.
420 LOK_CALLBACK_VIEW_LOCK = 29,
423 * The size of the change tracking table has changed.
425 * The payload example:
427 * "redline": {
428 * "action": "Remove",
429 * "index": "1",
430 * "author": "Unknown Author",
431 * "type": "Delete",
432 * "comment": "",
433 * "description": "Delete 'abc'",
434 * "dateTime": "2016-08-18T12:14:00"
438 * The format is the same as an entry of
439 * lok::Document::getCommandValues('.uno:AcceptTrackedChanges'), extra
440 * fields:
442 * - 'action' is either 'Add' or 'Remove', depending on if this is an
443 * insertion into the table or a removal.
445 LOK_CALLBACK_REDLINE_TABLE_SIZE_CHANGED = 30,
448 * An entry in the change tracking table has been modified.
450 * The payload example:
452 * "redline": {
453 * "action": "Modify",
454 * "index": "1",
455 * "author": "Unknown Author",
456 * "type": "Insert",
457 * "comment": "",
458 * "description": "Insert 'abcd'",
459 * "dateTime": "2016-08-18T13:13:00"
463 * The format is the same as an entry of
464 * lok::Document::getCommandValues('.uno:AcceptTrackedChanges'), extra
465 * fields:
467 * - 'action' is 'Modify'.
469 LOK_CALLBACK_REDLINE_TABLE_ENTRY_MODIFIED = 31,
472 * There is some change in comments in the document
474 * The payload example:
476 * "comment": {
477 * "action": "Add",
478 * "id": "11",
479 * "parent": "4",
480 * "author": "Unknown Author",
481 * "text": "",
482 * "dateTime": "2016-08-18T13:13:00",
483 * "anchorPos": "4529, 3906",
484 * "textRange": "1418, 3906, 3111, 919"
488 * The format is the same as an entry of
489 * lok::Document::getCommandValues('.uno:ViewAnnotations'), extra
490 * fields:
492 * - 'action' can be 'Add', 'Remove' or 'Modify' depending on whether
493 * comment has been added, removed or modified.
495 LOK_CALLBACK_COMMENT = 32,
498 * The column/row header is no more valid because of a column/row insertion
499 * or a similar event. Clients must query a new column/row header set.
501 * The payload says if we are invalidating a row or column header.
503 LOK_CALLBACK_INVALIDATE_HEADER = 33,
505 * The text content of the address field in Calc.
507 LOK_CALLBACK_CELL_ADDRESS = 34
510 LibreOfficeKitCallbackType;
512 typedef enum
514 /// A key on the keyboard is pressed.
515 LOK_KEYEVENT_KEYINPUT,
516 /// A key on the keyboard is released.
517 LOK_KEYEVENT_KEYUP
519 LibreOfficeKitKeyEventType;
521 typedef enum
523 /// A pressed gesture has started.
524 LOK_MOUSEEVENT_MOUSEBUTTONDOWN,
525 /// A pressed gesture has finished.
526 LOK_MOUSEEVENT_MOUSEBUTTONUP,
527 /// A change has happened during a press gesture.
528 LOK_MOUSEEVENT_MOUSEMOVE
530 LibreOfficeKitMouseEventType;
532 typedef enum
534 /// The start of selection is to be adjusted.
535 LOK_SETTEXTSELECTION_START,
536 /// The end of selection is to be adjusted.
537 LOK_SETTEXTSELECTION_END,
538 /// Both the start and the end of selection is to be adjusted.
539 LOK_SETTEXTSELECTION_RESET
541 LibreOfficeKitSetTextSelectionType;
543 typedef enum
546 * A move or a resize action starts. It is assumed that there is a valid
547 * graphic selection (see LOK_CALLBACK_GRAPHIC_SELECTION) and the supplied
548 * coordinates are the ones the user tapped on.
550 * The type of the action is move by default, unless the coordinates are
551 * the position of a handle (see below), in which case it's a resize.
553 * There are 8 handles for a graphic selection:
554 * - top-left, top-center, top-right
555 * - middle-left, middle-right
556 * - bottom-left, bottom-center, bottom-right
558 LOK_SETGRAPHICSELECTION_START,
560 * A move or resize action stops. It is assumed that this is always used
561 * only after a LOK_SETTEXTSELECTION_START. The supplied coordinates are
562 * the ones where the user released the screen.
564 LOK_SETGRAPHICSELECTION_END
566 LibreOfficeKitSetGraphicSelectionType;
568 #endif // defined LOK_USE_UNSTABLE_API || defined LIBO_INTERNAL_ONLY
570 #ifdef __cplusplus
572 #endif
574 #endif // INCLUDED_LIBREOFFICEKIT_LIBREOFFICEKITENUMS_H
576 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */