include/LibreOfficeKit/LibreOfficeKitGtk.h

   1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   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  */
   9
  10 #ifndef INCLUDED_LIBREOFFICEKIT_LIBREOFFICEKITGTK_H
  11 #define INCLUDED_LIBREOFFICEKIT_LIBREOFFICEKITGTK_H
  12
  13 #include <gtk/gtk.h>
  14 #include <gdk/gdk.h>
  15
  16 #include <LibreOfficeKit/LibreOfficeKit.h>
  17
  18 G_BEGIN_DECLS
  19
  20 #define LOK_TYPE_DOC_VIEW            (lok_doc_view_get_type())
  21 #define LOK_DOC_VIEW(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj), LOK_TYPE_DOC_VIEW, LOKDocView))
  22 #define LOK_IS_DOC_VIEW(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj), LOK_TYPE_DOC_VIEW))
  23 #define LOK_DOC_VIEW_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass),  LOK_TYPE_DOC_VIEW, LOKDocViewClass))
  24 #define LOK_IS_DOC_VIEW_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),  LOK_TYPE_DOC_VIEW))
  25 #define LOK_DOC_VIEW_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj),  LOK_TYPE_DOC_VIEW, LOKDocViewClass))
  26
  27 typedef struct _LOKDocView        LOKDocView;
  28 typedef struct _LOKDocViewClass   LOKDocViewClass;
  29 typedef struct _LOKDocViewPrivate LOKDocViewPrivate;
  30
  31 struct _LOKDocView
  32 {
  33     GtkDrawingArea aDrawingArea;
  34 };
  35
  36 struct _LOKDocViewClass
  37 {
  38     GtkDrawingAreaClass parent_class;
  39 };
  40
  41 GType                          lok_doc_view_get_type               (void) G_GNUC_CONST;
  42
  43 /**
  44  * lok_doc_view_new:
  45  * @pPath: (nullable) (allow-none): LibreOffice install path. Pass null to set it to default
  46  * path which in most cases would be $libdir/libreoffice/program
  47  * @cancellable: The cancellable object that you can use to cancel this
  48  * operation.
  49  * @error: The error that will be set if the object fails to initialize.
  50  *
  51  * Returns: (transfer none): The #LOKDocView widget instance.
  52  */
  53 GtkWidget*                     lok_doc_view_new                    (const gchar* pPath,
  54                                                                     GCancellable *cancellable,
  55                                                                     GError **error);
  56
  57 /**
  58  * lok_doc_view_new_from_user_profile:
  59  * @pPath: (nullable) (allow-none): LibreOffice install path. Pass null to set it to default
  60  * path which in most cases would be $libdir/libreoffice/program
  61  * @pUserProfile: (nullable) (allow-none): User profile URL. Must be either a file URL or a
  62  * special vnd.sun.star.pathname URL. Pass non-null to be able to use this
  63  * widget and LibreOffice itself in parallel.
  64  * @cancellable: The cancellable object that you can use to cancel this
  65  * operation.
  66  * @error: The error that will be set if the object fails to initialize.
  67  *
  68  * Returns: (transfer none): The #LOKDocView widget instance.
  69  */
  70 GtkWidget*                     lok_doc_view_new_from_user_profile  (const gchar* pPath,
  71                                                                     const gchar* pUserProfile,
  72                                                                     GCancellable *cancellable,
  73                                                                     GError **error);
  74
  75 /**
  76  * lok_doc_view_new_from_widget:
  77  * @pDocView: The #LOKDocView instance
  78  * @pRenderingArguments: (nullable) (allow-none): lok::Document::initializeForRendering() arguments.
  79  *
  80  * Returns: (transfer none): The #LOKDocView widget instance.
  81  */
  82 GtkWidget*                     lok_doc_view_new_from_widget        (LOKDocView* pDocView,
  83                                                                     const gchar* pRenderingArguments);
  84
  85 /**
  86  * lok_doc_view_open_document:
  87  * @pDocView: The #LOKDocView instance
  88  * @pPath: (transfer full): The path of the document that #LOKDocView widget should try to open
  89  * @pRenderingArguments: (nullable) (allow-none): lok::Document::initializeForRendering() arguments.
  90  * @cancellable:
  91  * @callback:
  92  * @userdata:
  93  */
  94 void                           lok_doc_view_open_document          (LOKDocView* pDocView,
  95                                                                     const gchar* pPath,
  96                                                                     const gchar* pRenderingArguments,
  97                                                                     GCancellable* cancellable,
  98                                                                     GAsyncReadyCallback callback,
  99                                                                     gpointer userdata);
 100
 101 /**
 102  * lok_doc_view_open_document_finish:
 103  * @pDocView: The #LOKDocView instance
 104  * @res:
 105  * @error:
 106  *
 107  * Returns: %TRUE if the document is loaded successfully, %FALSE otherwise
 108  */
 109 gboolean                       lok_doc_view_open_document_finish   (LOKDocView* pDocView,
 110                                                                     GAsyncResult* res,
 111                                                                     GError** error);
 112
 113 /**
 114  * lok_doc_view_get_document:
 115  * @pDocView: The #LOKDocView instance
 116  *
 117  * Gets the document the viewer displays.
 118  *
 119  * Returns: The #LibreOfficeKitDocument instance the widget is currently showing
 120  */
 121 LibreOfficeKitDocument*        lok_doc_view_get_document           (LOKDocView* pDocView);
 122
 123 /**
 124  * lok_doc_view_set_zoom:
 125  * @pDocView: The #LOKDocView instance
 126  * @fZoom: The new zoom level that pDocView must set it into.
 127  *
 128  * Sets the new zoom level for the widget. Does nothing if fZoom is equal to
 129  * existing zoom level. Values outside the range [0.25, 5.0] are clamped into
 130  * the nearest allowed value in the interval.
 131  */
 132 void                           lok_doc_view_set_zoom               (LOKDocView* pDocView,
 133                                                                     float fZoom);
 134 /**
 135  * lok_doc_view_set_visible_area:
 136  * @pDocView: The #LOKDocView instance
 137  * @pVisibleArea: The new visible area of pDocView in twips.
 138  *
 139  * Sets the new visible area of the widget. This helps e.g. the page down key
 140  * to jump the correct length, which depends on the amount of visible height of
 141  * the document.
 142  */
 143 void                           lok_doc_view_set_visible_area       (LOKDocView* pDocView,
 144                                                                     GdkRectangle* pVisibleArea);
 145
 146 /**
 147  * lok_doc_view_get_zoom:
 148  * @pDocView: The #LOKDocView instance
 149  *
 150  * Returns: The current zoom factor value in float for pDocView
 151  */
 152 gfloat                         lok_doc_view_get_zoom               (LOKDocView* pDocView);
 153
 154 /**
 155  * lok_doc_view_get_parts:
 156  * @pDocView: The #LOKDocView instance
 157  *
 158  * Returns: Part refers to either individual sheets in a Calc, or slides in Impress,
 159  * and has no relevance for Writer. Returns -1 if no document is set currently.
 160  */
 161 gint                           lok_doc_view_get_parts              (LOKDocView* pDocView);
 162
 163 /**
 164  * lok_doc_view_get_part:
 165  * @pDocView: The #LOKDocView instance
 166  *
 167  * Returns: Current part number of the document. Returns -1 if no document is set currently.
 168  */
 169 gint                           lok_doc_view_get_part               (LOKDocView* pDocView);
 170
 171 /**
 172  * lok_doc_view_set_part:
 173  * @pDocView: The #LOKDocView instance
 174  * @nPart:
 175  */
 176 void                           lok_doc_view_set_part               (LOKDocView* pDocView,
 177                                                                     int nPart);
 178
 179 /**
 180  * lok_doc_view_get_part_name:
 181  * @pDocView: The #LOKDocView instance
 182  * @nPart:
 183  *
 184  * Returns: Get current part name of loaded document. Returns null if no
 185  * document is set, or document has been destroyed using lok_doc_view_destroy_document.
 186  */
 187 gchar*                         lok_doc_view_get_part_name          (LOKDocView* pDocView,
 188                                                                     int nPart);
 189
 190 /**
 191  * lok_doc_view_set_partmode:
 192  * @pDocView: The #LOKDocView instance
 193  * @nPartMode:
 194  */
 195 void                           lok_doc_view_set_partmode           (LOKDocView* pDocView,
 196                                                                     int nPartMode);
 197
 198 /**
 199  * lok_doc_view_reset_view:
 200  * @pDocView: The #LOKDocView instance
 201  */
 202 void                           lok_doc_view_reset_view             (LOKDocView* pDocView);
 203
 204 /**
 205  * lok_doc_view_set_edit:
 206  * @pDocView: The #LOKDocView instance
 207  * @bEdit: %TRUE if the pDocView should go in edit mode, %FALSE otherwise
 208  *
 209  * Sets if the viewer is actually an editor or not.
 210  */
 211 void                           lok_doc_view_set_edit               (LOKDocView* pDocView,
 212                                                                     gboolean bEdit);
 213
 214 /**
 215  * lok_doc_view_get_edit:
 216  * @pDocView: The #LOKDocView instance
 217  *
 218  * Gets if the viewer is actually an editor or not.
 219  *
 220  * Returns: %TRUE if the given pDocView is in edit mode.
 221  */
 222 gboolean                       lok_doc_view_get_edit               (LOKDocView* pDocView);
 223
 224 /**
 225  * lok_doc_view_post_command:
 226  * @pDocView: the #LOKDocView instance
 227  * @pCommand: the command to issue to LO core
 228  * @pArguments: the arguments to the given command
 229  * @bNotifyWhenFinished: normally false, but it may be useful for eg. .uno:Save
 230  *
 231  * Posts the .uno: command to the LibreOfficeKit.
 232  */
 233 void                           lok_doc_view_post_command           (LOKDocView* pDocView,
 234                                                                     const gchar* pCommand,
 235                                                                     const gchar* pArguments,
 236                                                                     gboolean bNotifyWhenFinished);
 237
 238
 239 /**
 240  * lok_doc_view_find_next:
 241  * @pDocView: The #LOKDocView instance
 242  * @pText: text to search for
 243  * @bHighlightAll: Whether all the matches should be highlighted or not
 244  *
 245  * Highlights the next matching text in the view. `search-not-found` signal will
 246  * be emitted when no search is found
 247  */
 248 void                           lok_doc_view_find_next              (LOKDocView* pDocView,
 249                                                                     const gchar* pText,
 250                                                                     gboolean bHighlightAll);
 251
 252 /**
 253  * lok_doc_view_find_prev:
 254  * @pDocView: The #LOKDocView instance
 255  * @pText: text to search for
 256  * @bHighlightAll: Whether all the matches should be highlighted or not
 257  *
 258  * Highlights the previous matching text in the view. `search-not-found` signal
 259  * will be emitted when no search is found
 260  */
 261 void                           lok_doc_view_find_prev              (LOKDocView* pDocView,
 262                                                                     const gchar* pText,
 263                                                                     gboolean bHighlightAll);
 264
 265 /**
 266  * lok_doc_view_highlight_all:
 267  * @pDocView: The #LOKDocView instance
 268  * @pText: text to search for
 269  *
 270  * Highlights all matching texts in the view. `search-not-found` signal
 271  * will be emitted when no search is found
 272  */
 273 void                           lok_doc_view_highlight_all          (LOKDocView* pDocView,
 274                                                                     const gchar* pText);
 275
 276 /**
 277  * lok_doc_view_copy_selection:
 278  * @pDocView: The #LOKDocView instance
 279  * @pMimeType: suggests the return format, for example text/plain;charset=utf-8
 280  * @pUsedMimeType: (out): output parameter to inform about the determined format
 281  * (suggested or plain text).
 282  *
 283  * Returns: Selected text. The caller must free the returned buffer after
 284  * use. Returns null if no document is set.
 285  */
 286 gchar*                          lok_doc_view_copy_selection        (LOKDocView* pDocView,
 287                                                                     const gchar* pMimeType,
 288                                                                     gchar** pUsedMimeType);
 289
 290 /**
 291  * lok_doc_view_paste:
 292  * @pDocView: The #LOKDocView instance
 293  * @pMimeType: format of pData, for example text/plain;charset=utf-8
 294  * @pData: the data to be pasted
 295  * @nSize: length of data to be pasted
 296  *
 297  * Pastes the content at the current cursor position
 298  *
 299  * Returns: if pData was pasted successfully.
 300  */
 301 gboolean                        lok_doc_view_paste                 (LOKDocView* pDocView,
 302                                                                     const gchar* pMimeType,
 303                                                                     const gchar* pData,
 304                                                                     gsize nSize);
 305
 306 /**
 307  * lok_doc_view_set_document_password:
 308  * @pDocView: The #LOKDocView instance
 309  * @pURL: the URL of the document to set password for, as sent with signal `password-required`
 310  * @pPassword: (nullable) (allow-none): the password, NULL for no password
 311  *
 312  * Set the password for password protected documents
 313  */
 314 void                            lok_doc_view_set_document_password (LOKDocView* pDocView,
 315                                                                     const gchar* pURL,
 316                                                                     const gchar* pPassword);
 317
 318 /**
 319  * lok_doc_view_get_version_info:
 320  * @pDocView: The #LOKDocView instance
 321  *
 322  * Get version information of the LOKit process
 323  *
 324  * Returns: JSON string containing version information in format:
 325  * {ProductName: <>, ProductVersion: <>, ProductExtension: <>, BuildId: <>}
 326  *
 327  * Eg: {"ProductName": "LibreOffice",
 328  * "ProductVersion": "5.3",
 329  * "ProductExtension": ".0.0.alpha0",
 330  * "BuildId": "<full 40 char git hash>"}
 331  */
 332 gchar*                         lok_doc_view_get_version_info       (LOKDocView* pDocView);
 333
 334 /**
 335  * lok_doc_view_pixel_to_twip:
 336  * @pDocView: The #LOKDocView instance
 337  * @fInput: The value in pixels to convert to twips
 338  *
 339  * Converts the value in pixels to twips according to zoom level.
 340  *
 341  * Returns: The corresponding value in twips
 342  */
 343 gfloat                         lok_doc_view_pixel_to_twip          (LOKDocView* pDocView,
 344                                                                     float fInput);
 345
 346 /**
 347  * lok_doc_view_twip_to_pixel:
 348  * @pDocView: The #LOKDocView instance
 349  * @fInput: The value in twips to convert to pixels
 350  *
 351  * Converts the value in twips to pixels according to zoom level.
 352  *
 353  * Returns: The corresponding value in pixels
 354  */
 355 gfloat                         lok_doc_view_twip_to_pixel          (LOKDocView* pDocView,
 356                                                                     float fInput);
 357
 358 G_END_DECLS
 359
 360 #endif // INCLUDED_LIBREOFFICEKIT_LIBREOFFICEKITGTK_H
 361
 362 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */