okular/core/form.h

   1 /***************************************************************************
   2  *   Copyright (C) 2007 by Pino Toscano <pino@kde.org>                     *
   3  *                                                                         *
   4  *   This program is free software; you can redistribute it and/or modify  *
   5  *   it under the terms of the GNU General Public License as published by  *
   6  *   the Free Software Foundation; either version 2 of the License, or     *
   7  *   (at your option) any later version.                                   *
   8  ***************************************************************************/
   9
  10 #ifndef _OKULAR_FORM_H_
  11 #define _OKULAR_FORM_H_
  12
  13 #include <okular/core/okular_export.h>
  14 #include <okular/core/area.h>
  15
  16 #include <QtCore/QStringList>
  17
  18 namespace Okular {
  19
  20 class Action;
  21 class Page;
  22 class PagePrivate;
  23 class FormFieldPrivate;
  24 class FormFieldButtonPrivate;
  25 class FormFieldTextPrivate;
  26 class FormFieldChoicePrivate;
  27
  28 /**
  29  * @short The base interface of a form field.
  30  *
  31  * This is the very basic interface to represent a field in a form.
  32  *
  33  * This is not meant to be used as a direct base for the form fields in a
  34  * document, but its abstract subclasses are.
  35  */
  36 class OKULAR_EXPORT FormField
  37 {
  38     /// @cond PRIVATE
  39     friend class Page;
  40     friend class PagePrivate;
  41     /// @endcond
  42
  43     public:
  44         /**
  45          * The types of form field.
  46          */
  47         enum FieldType
  48         {
  49             FormButton,      ///< A "button". See @ref FormFieldButton::ButtonType.
  50             FormText,        ///< A field of variable text. See @ref FormFieldText::TextType.
  51             FormChoice,      ///< A choice field. See @ref FormFieldChoice::ChoiceType.
  52             FormSignature    ///< A signature.
  53         };
  54
  55         virtual ~FormField();
  56
  57         /**
  58          * The type of the field.
  59          */
  60         FieldType type() const;
  61
  62         /**
  63          * The bouding rect of the field, in normalized coordinates.
  64          */
  65         virtual NormalizedRect rect() const = 0;
  66
  67         /**
  68          * The ID of the field.
  69          */
  70         virtual int id() const = 0;
  71
  72         /**
  73          * The internal name of the field, to be used when referring to the
  74          * field in eg scripts.
  75          */
  76         virtual QString name() const = 0;
  77
  78         /**
  79          * The visible name of the field, to be used in the user interface
  80          * (eg in error messages, etc).
  81          */
  82         virtual QString uiName() const = 0;
  83
  84         /**
  85          * Whether the field is read-only.
  86          */
  87         virtual bool isReadOnly() const;
  88
  89         /**
  90          * Whether this form field is visible.
  91          */
  92         virtual bool isVisible() const;
  93
  94         Action* activationAction() const;
  95
  96     protected:
  97         /// @cond PRIVATE
  98         FormField( FormFieldPrivate &dd );
  99         Q_DECLARE_PRIVATE( FormField )
 100         FormFieldPrivate *d_ptr;
 101         /// @endcond
 102
 103         void setActivationAction( Action *action );
 104
 105     private:
 106         Q_DISABLE_COPY( FormField )
 107 };
 108
 109
 110 /**
 111  * @short Interface of a button form field.
 112  *
 113  * This is the base interface to reimplement to represent a button field, like
 114  * a push button, a check box or a radio button.
 115  *
 116  * @since 0.7 (KDE 4.1)
 117  */
 118 class OKULAR_EXPORT FormFieldButton : public FormField
 119 {
 120     public:
 121         /**
 122          * The types of button field.
 123          */
 124         enum ButtonType
 125         {
 126             Push,          ///< A simple push button.
 127             CheckBox,      ///< A check box.
 128             Radio          ///< A radio button.
 129         };
 130
 131         virtual ~FormFieldButton();
 132
 133         /**
 134           The particular type of the button field.
 135          */
 136         virtual ButtonType buttonType() const = 0;
 137
 138         /**
 139          * The caption to be used for the button.
 140          */
 141         virtual QString caption() const = 0;
 142
 143         /**
 144          * The state of the button.
 145          */
 146         virtual bool state() const = 0;
 147
 148         /**
 149          * Sets the state of the button to the new \p state .
 150          */
 151         virtual void setState( bool state );
 152
 153         /**
 154          * The list with the IDs of siblings (ie, buttons belonging to the same
 155          * group as the current one.
 156          *
 157          * Valid only for \ref Radio buttons, an empty list otherwise.
 158          */
 159         virtual QList< int > siblings() const = 0;
 160
 161     protected:
 162         FormFieldButton();
 163
 164     private:
 165         Q_DECLARE_PRIVATE( FormFieldButton )
 166         Q_DISABLE_COPY( FormFieldButton )
 167 };
 168
 169
 170 /**
 171  * @short Interface of a text form field.
 172  *
 173  * This is the base interface to reimplement to represent a text field, ie a
 174  * field where the user insert text.
 175  */
 176 class OKULAR_EXPORT FormFieldText : public FormField
 177 {
 178     public:
 179         /**
 180          * The types of text field.
 181          */
 182         enum TextType
 183         {
 184             Normal,        ///< A simple singleline text field.
 185             Multiline,     ///< A multiline text field.
 186             FileSelect     ///< An input field to select the path of a file on disk.
 187         };
 188
 189         virtual ~FormFieldText();
 190
 191         /**
 192          * The particular type of the text field.
 193          */
 194         virtual TextType textType() const = 0;
 195
 196         /**
 197          * The text of text field.
 198          */
 199         virtual QString text() const = 0;
 200
 201         /**
 202          * Sets the new @p text in the text field.
 203          *
 204          * The default implementation does nothing.
 205          *
 206          * Reimplemented only if the setting of new text is supported.
 207          */
 208         virtual void setText( const QString& text );
 209
 210         /**
 211          * Whether this text field is a password input, eg its text @b must be
 212          * replaced with asterisks.
 213          *
 214          * Always false for @ref FileSelect text fields.
 215          */
 216         virtual bool isPassword() const;
 217
 218         /**
 219          * Whether this text field should allow rich text.
 220          */
 221         virtual bool isRichText() const;
 222
 223         /**
 224          * The maximum length allowed for the text of text field, or -1 if
 225          * there is no limitation for the text.
 226          */
 227         virtual int maximumLength() const;
 228
 229         /**
 230          * The alignment of the text within the field.
 231          */
 232         virtual Qt::Alignment textAlignment() const;
 233
 234         /**
 235          * Whether the text inserted manually in the field (where possible)
 236          * can be spell-checked.
 237          *
 238          * @note meaningful only if the field is editable.
 239          */
 240         virtual bool canBeSpellChecked() const;
 241
 242     protected:
 243         FormFieldText();
 244
 245     private:
 246         Q_DECLARE_PRIVATE( FormFieldText )
 247         Q_DISABLE_COPY( FormFieldText )
 248 };
 249
 250
 251 /**
 252  * @short Interface of a choice form field.
 253  *
 254  * This is the base interface to reimplement to represent a choice field, ie a
 255  * field where the user can select one (of more) element(s) among a set of
 256  * choices.
 257  */
 258 class OKULAR_EXPORT FormFieldChoice : public FormField
 259 {
 260     public:
 261         /**
 262          * The types of choice field.
 263          */
 264         enum ChoiceType
 265         {
 266             ComboBox,     ///< A combo box choice field.
 267             ListBox       ///< A list box choice field.
 268         };
 269
 270         virtual ~FormFieldChoice();
 271
 272         /**
 273          * The particular type of the choice field.
 274          */
 275         virtual ChoiceType choiceType() const = 0;
 276
 277         /**
 278          * The possible choices of the choice field.
 279          */
 280         virtual QStringList choices() const = 0;
 281
 282         /**
 283          * Whether this ComboBox is editable, ie the user can type in a custom
 284          * value.
 285          *
 286          * Always false for the other types of choices.
 287          */
 288         virtual bool isEditable() const;
 289
 290         /**
 291          * Whether more than one choice of this ListBox can be selected at the
 292          * same time.
 293          *
 294          * Always false for the other types of choices.
 295          */
 296         virtual bool multiSelect() const;
 297
 298         /**
 299          * The currently selected choices.
 300          *
 301          * Always one element in the list in case of single choice elements.
 302          */
 303         virtual QList< int > currentChoices() const = 0;
 304
 305         /**
 306          * Sets the selected choices to @p choices .
 307          */
 308         virtual void setCurrentChoices( const QList< int >& choices );
 309
 310         /**
 311          * The alignment of the text within the field.
 312          */
 313         virtual Qt::Alignment textAlignment() const;
 314
 315         /**
 316          * Whether the text inserted manually in the field (where possible)
 317          * can be spell-checked.
 318          *
 319          * @note meaningful only if the field is editable.
 320          */
 321         virtual bool canBeSpellChecked() const;
 322
 323     protected:
 324         FormFieldChoice();
 325
 326     private:
 327         Q_DECLARE_PRIVATE( FormFieldChoice )
 328         Q_DISABLE_COPY( FormFieldChoice )
 329 };
 330
 331 }
 332
 333 #endif