librss/textinput.h

   1 /*
   2  * textinput.h
   3  *
   4  * Copyright (c) 2001, 2002, 2003, 2004 Frerich Raabe <raabe@kde.org>
   5  *
   6  * This program is distributed in the hope that it will be useful, but WITHOUT
   7  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
   8  * FOR A PARTICULAR PURPOSE. For licensing and distribution details, check the
   9  * accompanying file 'COPYING'.
  10  */
  11 #ifndef LIBRSS_TEXTINPUT_H
  12 #define LIBRSS_TEXTINPUT_H
  13
  14 #include "global.h"
  15
  16 class KURL;
  17
  18 class QDomNode;
  19 class QString;
  20
  21 namespace RSS
  22 {
  23         /**
  24          * Represents a text input facility as stored in a RSS file for the purpose
  25          * of allowing users to submit queries back to the publisher's site. You
  26          * don't have to instantiate one of these yourself, the common way to access
  27          * instances is via Document::textInput().
  28          * @see Document::textInput()
  29          */
  30         class TextInput
  31         {
  32                 public:
  33                         /**
  34                          * Default constructor.
  35                          */
  36                         TextInput();
  37
  38                         /**
  39                          * Copy constructor.
  40                          * @param other The TextInput object to copy.
  41                          */
  42                         TextInput(const TextInput &other);
  43
  44                         /**
  45                          * Constructs a TextInput from a piece of RSS markup.
  46                          * @param node A QDomNode which references the DOM leaf to be used
  47                          * for constructing the TextInput.
  48                          */
  49                         TextInput(const QDomNode &node);
  50
  51                         /**
  52                          * Assignment operator.
  53                          * @param other The TextInput object to clone.
  54                          * @return A reference to the cloned TextInput object.
  55                          */
  56                         TextInput &operator=(const TextInput &other);
  57
  58                         /**
  59                          * Compares two text inputs. Two text inputs are considered
  60                          * identical if their properties (title, description, link etc.)
  61                          * are identical.
  62                          * @param other The text input to compare with.
  63                          * @return Whether the two text inputs are equal.
  64                          */
  65                         bool operator==(const TextInput &other) const;
  66
  67                         /**
  68                          * Convenience method. Simply calls !operator==().
  69                          * @param other The text input to compared with.
  70                          * @return Whether the two text inputs are unequal.
  71                          */
  72                         bool operator!=(const TextInput &other) const { return !operator==(other); }
  73
  74                         /**
  75                          * Destructor.
  76                          */
  77                         virtual ~TextInput();
  78
  79                         /**
  80                          * RSS 0.90 and upwards
  81                          * @return The title (often a label to be used for the input field)
  82                          * of the text input, or QString::null if no title is available.
  83                          */
  84                         QString title() const;
  85
  86                         /**
  87                          * RSS 0.90 and upwards
  88                          * @return The description (usually used as a tooltip which appears
  89                          * if the mouse hovers above the input field for a short time) of
  90                          * the text input, or QString::null if no description is
  91                          * available.
  92                          */
  93                         QString description() const;
  94
  95                         /**
  96                          * RSS 0.90 and upwards
  97                          * @return The name of the text input (what's this for?) of the
  98                          * text input, or QString::null, if no name is available.
  99                          */
 100                         QString name() const;
 101
 102                         /**
 103                          * RSS 0.90 and upwards
 104                          * @return A link to which the contents of the input field should
 105                          * be sent after the user specified them. This is often a CGI
 106                          * program on a remote server which evaluates the entered
 107                          * information. An empty KURL is returned in case no link is
 108                          * available.
 109                          * Note that the RSS 0.91 Specification dictates that URLs not
 110                          * starting with "http://" or "ftp://" are considered invalid.
 111                          */
 112                         const KURL &link() const;
 113
 114                 private:
 115                         struct Private;
 116                         Private *d;
 117         };
 118 }
 119
 120 #endif // LIBRSS_TEXTINPUT_H
 121 // vim: noet:ts=4