Edit remaining documentation.

include/frames/environment.h

@@ -38,7 +38,7 @@ namespace Frames {
   typedef Ptr<Environment> EnvironmentPtr;
   class Frame;
   class Layout;
-  class VerbBase;
+  class VerbGeneric;
 
   namespace detail {
     class CharacterInfo;

include/frames/event.h

@@ -33,26 +33,26 @@ namespace Frames {
   /** This contains all members of Verb that do not require information about the verb parameter types.
 
   See Verb for detailed information. */
-  class VerbBase : detail::Noncopyable {
+  class VerbGeneric : detail::Noncopyable {
   public:
     /// Returns human-readable name for this Verb.
     const char *NameGet() const { return m_name; }
 
-    /// Gets this verb's Dive version.
-    /** Guaranteed to return null if this verb is a Dive or Bubble. */
-    const VerbBase *DiveGet() const { return m_dive; }
-    /// Gets this verb's Bubble version.
-    /** Guaranteed to return null if this verb is a Dive or Bubble. */
-    const VerbBase *BubbleGet() const { return m_bubble; }
+    /// Gets this verb's Dive variant.
+    /** Returns null if this verb is a Dive or Bubble. */
+    const VerbGeneric *DiveGet() const { return m_dive; }
+    /// Gets this verb's Bubble variant.
+    /** Returns null if this verb is a Dive or Bubble. */
+    const VerbGeneric *BubbleGet() const { return m_bubble; }
 
   private:
     template <typename Parameters> friend class Verb;
-    VerbBase(const char *name) : m_name(name), m_dive(0), m_bubble(0) {};
-    VerbBase(const char *name, const VerbBase *dive, const VerbBase *bubble) : m_name(name), m_dive(dive), m_bubble(bubble) {};
+    VerbGeneric(const char *name) : m_name(name), m_dive(0), m_bubble(0) {};
+    VerbGeneric(const char *name, const VerbGeneric *dive, const VerbGeneric *bubble) : m_name(name), m_dive(dive), m_bubble(bubble) {};
 
     const char *m_name;
-    const VerbBase *m_dive;
-    const VerbBase *m_bubble;
+    const VerbGeneric *m_dive;
+    const VerbGeneric *m_bubble;
   };
 
   /// Passed along with every event call for storing event metainformation and providing callbacks.
@@ -65,45 +65,45 @@ namespace Frames {
 
     /// Returns the Verb this event refers to.
     /** If this is part of a Dive or Bubble series, this will return the specific Verb that is being called. */
-    const VerbBase *VerbGet() const { return m_verb; }
+    const VerbGeneric *VerbGet() const { return m_verb; }
 
     /// Returns the Layout this event is currently traversing.
     /** If this is not part of a Dive or Bubble series, this will be equivalent to TargetGet. */
     Layout *TargetContextGet() const { return m_targetContext; }
 
     /// Returns the Verb this event is currently traversing.
     /** If this is not part of a Dive or Bubble series, this will be equivalent to VerbGet. */
-    const VerbBase *VerbContextGet() const { return m_verbContext; }
+    const VerbGeneric *VerbContextGet() const { return m_verbContext; }
 
   private:
     friend class Layout;
 
-    Handle(Layout *target, const VerbBase *verb) : m_target(target), m_verb(verb), m_targetContext(target), m_verbContext(verb) {}
+    Handle(Layout *target, const VerbGeneric *verb) : m_target(target), m_verb(verb), m_targetContext(target), m_verbContext(verb) {}
     ~Handle() {} // TODO - clean up handles in Lua?
 
-    void SetContext(Layout *target, const VerbBase *verb) {
+    void SetContext(Layout *target, const VerbGeneric *verb) {
       m_targetContext = target;
       m_verbContext = verb;
     }
 
     Layout *m_target;
-    const VerbBase *m_verb;
+    const VerbGeneric *m_verb;
 
     Layout *m_targetContext;
-    const VerbBase *m_verbContext;
+    const VerbGeneric *m_verbContext;
   };
 
   /// Represents a type of event with specific parameter typing.
   /** A Verb represents an event category that can be called on a Layout. */
-  template <typename Parameters> class Verb : public VerbBase {
+  template <typename Parameters> class Verb : public VerbGeneric {
   private:
     friend class VerbPackage<Parameters>;
-    Verb(const char *name, const Verb<Parameters> *dive, const Verb<Parameters> *bubble) : VerbBase(name, dive, bubble) { };
+    Verb(const char *name, const Verb<Parameters> *dive, const Verb<Parameters> *bubble) : VerbGeneric(name, dive, bubble) { };
 
   public:
     /// Constructor for standalone Verbs.
     /** Do not call manually - at the moment, it is required that you use FRAMES_VERB_DECLARE/FRAMES_VERB_DEFINE. */
-    Verb(const char *name) : VerbBase(name) { };
+    Verb(const char *name) : VerbGeneric(name) { };
 
     /// Convenience typedef for the function type which is needed to attach to this Verb.
     typedef typename detail::FunctionPrefix<Handle*, Parameters>::T TypeHandler;

include/frames/layout.h

@@ -227,11 +227,11 @@ namespace Frames {
     };
 
     typedef std::multiset<Callback, Callback::Sorter> EventMultiset;
-    typedef std::map<const VerbBase *, std::multiset<Callback, Callback::Sorter> > EventLookup;
+    typedef std::map<const VerbGeneric *, std::multiset<Callback, Callback::Sorter> > EventLookup;
 
     class CallbackIterator : detail::Noncopyable {
     public:
-      CallbackIterator(Layout *target, const VerbBase *event);
+      CallbackIterator(Layout *target, const VerbGeneric *event);
       ~CallbackIterator();
 
       void Setup(Handle *handle) {
@@ -246,7 +246,7 @@ namespace Frames {
       void IndexNext();
 
       Layout *LayoutGet();
-      const VerbBase *VerbGet();
+      const VerbGeneric *VerbGet();
 
       enum State { STATE_DIVE, STATE_MAIN, STATE_BUBBLE, STATE_COMPLETE };
       State m_state;
@@ -255,7 +255,7 @@ namespace Frames {
       int m_diveIndex;
 
       Layout *m_target;
-      const VerbBase *m_event;
+      const VerbGeneric *m_event;
 
       EventMultiset::iterator m_current;
       EventMultiset::iterator m_last;
@@ -390,14 +390,14 @@ namespace Frames {
     template <typename P1> void EventTrigger(const Verb<void (P1)> &event, typename detail::MakeConstRef<P1>::T p1);
 
     /// Determines if a verb is hooked.
-    bool EventHooked(const VerbBase &event) const;
+    bool EventHooked(const VerbGeneric &event) const;
 
     // --------- Misc
 
     /// Mode for input handling.
     enum InputMode {
-      IM_NONE, //< Indicates that the frame should not accept input of any kind; any input will pass through transparently.
-      IM_ALL, //< Indicates that the frame should accept all kinds of input, and input will not pass to a frame below this one.
+      IM_NONE, ///< Indicates that the frame should not accept input of any kind; any input will pass through transparently.
+      IM_ALL, ///< Indicates that the frame should accept all kinds of input, and input will not pass to a frame below this one.
       IM_COUNT,
     };
     /// Sets the input mode.

include/frames/text.h

@@ -47,7 +47,7 @@ namespace Frames {
     /** See \ref basicsresources "Resources" for details on Frames's resource system. */
     void FontSet(const std::string &id);
     /// Gets the ID of the font used to render text.
-    const std::string &GetFont() const { return m_font; }
+    const std::string &FontGet() const { return m_font; }
 
     /// Sets the size of the font.
     /** This is currently in arbitrary undefined units - this will change at some point in the future. */
@@ -68,19 +68,20 @@ namespace Frames {
 
     /// List of interactivity settings allowed.
     enum InteractivityMode {
-      INTERACTIVE_NONE, //< No interactivity at all.
-      INTERACTIVE_SELECT, //< Allows text selection with the mouse, plus copy to clipboard.
-      INTERACTIVE_CURSOR, //< Allows a cursor, text selection with mouse and keyboard, and copy to clipboard.
-      INTERACTIVE_EDIT, //< Allows full text editing with mouse and keyboard.
+      INTERACTIVE_NONE, ///< No interactivity at all.
+      INTERACTIVE_SELECT, ///< Allows text selection with the mouse, plus copy to clipboard.
+      INTERACTIVE_CURSOR, ///< Allows a cursor, text selection with mouse and keyboard, and copy to clipboard.
+      INTERACTIVE_EDIT, ///< Allows full text editing with mouse and keyboard.
     };
     /// Sets the interactivity mode.
     void InteractiveSet(InteractivityMode interactive);
     /// Gets the interactivity mode.
     InteractivityMode InteractiveGet() const { return m_interactive; }
 
     /// Sets the cursor position.
-    /** Cursor position is done in terms of the character that the cursor is placed directly before.
+    /** Cursor position is done in terms of the byte that the cursor is placed directly before.
     0 places the cursor at the beginning of the textfield; TextGet().size() places the cursor at the end of the textfield.
+    Placing the character within a multibyte code point is undefined behavior.
     
     Also scrolls the textbox as appropriate to keep the cursor in view. */
     void CursorSet(int position);

include/frames/texture.h

@@ -38,9 +38,9 @@ namespace Frames {
 
     /// Pixel format. Not all formats make sense with all Types.
     enum Format {
-      FORMAT_RGBA_8, //< Color data with alpha channel. 8 bits per channel, 32 bits per pixel. Laid out as RGBA.
-      FORMAT_RGB_8, //< Color data, no alpha channel. 8 bits per channel, 24 bits per pixel. Laid out as RGB. Packed. Will be converted to RGBA for actual textures. Probably slower than FORMAT_RGBA.
-      FORMAT_R_8, //< Red only. 8 bits per channel, 8 bits per pixel.
+      FORMAT_RGBA_8, ///< Color data with alpha channel. 8 bits per channel, 32 bits per pixel. Laid out as RGBA.
+      FORMAT_RGB_8, ///< Color data, no alpha channel. 8 bits per channel, 24 bits per pixel. Laid out as RGB. Packed. Will be converted to RGBA for actual textures. Probably slower than FORMAT_RGBA.
+      FORMAT_R_8, ///< Red only. 8 bits per channel, 8 bits per pixel.
       FORMAT_COUNT,
     };
 
@@ -53,17 +53,12 @@ namespace Frames {
     /** If takeOwnership is true, the Texture will automatically deallocate data using the Environment's allocator. */
     static TexturePtr CreateRawUnmanaged(Environment *env, int width, int height, Format format, unsigned char *data, int stride, bool takeOwnership = false);
 
-    /// Creates a NIL Texture.
-    /** This is not valid to pass to any function expecting a Texture. */
-    Texture();
-    ~Texture();
-
     // ---- Generic data
 
     /// Texture type.
     enum Type {
-      NIL, //< Invalid texture used as a default value.
-      RAW, //< Raw byte array containing decompressed image data.
+      NIL, ///< Invalid texture used as a default value.
+      RAW, ///< Raw byte array containing decompressed image data in scanline order.
     };
     /// Returns the Type.
     Type TypeGet() const { return m_type; }
@@ -78,13 +73,15 @@ namespace Frames {
     // ---- Raw accessors
 
     /// Returns the raw data.
-    /** Not valid if this Texture type is not RAW. */
+    /** Undefined results if this Texture type is not RAW. */
     unsigned char *RawDataGet() { return m_raw_data; }
     /// Returns the raw data.
-    /** Not valid if this Texture type is not RAW. */
+    /** Undefined results if this Texture type is not RAW. */
     const unsigned char *RawDataGet() const { return m_raw_data; }
     /// Returns the raw data's stride.
-    /** Stride is the memory offset, in bytes, between rows of the texture. On densely-packed textures this will be WidthGet() * RawBPPGet(FormatGet()). It may be larger on textures with row padding. */
+    /** Stride is the memory offset, in bytes, between rows of the texture. On densely-packed textures this will be WidthGet() * RawBPPGet(FormatGet()). It may be larger on textures with row padding.
+    
+    Undefined results if this Texture type is not RAW. */
     int RawStrideGet() const { return m_raw_stride; }
 
     // ---- Helper functions
@@ -93,6 +90,11 @@ namespace Frames {
     static int RawBPPGet(Format format);
 
   private:
+    friend class Refcountable<Texture>;
+
+    Texture();
+    ~Texture();
+
     Type m_type;
 
     Format m_format;

src/core/layout.cpp

@@ -903,8 +903,8 @@ namespace Frames {
     ObliterateExtract();
   }
 
-  bool Layout::EventHooked(const VerbBase &event) const {
-    std::map<const VerbBase *, std::multiset<Callback, Callback::Sorter> >::const_iterator itr = m_events.find(&event);
+  bool Layout::EventHooked(const VerbGeneric &event) const {
+    std::map<const VerbGeneric *, std::multiset<Callback, Callback::Sorter> >::const_iterator itr = m_events.find(&event);
     if (itr == m_events.end()) {
       // no handles, we're good
       return false;
@@ -1116,7 +1116,7 @@ namespace Frames {
 
   //Layout::CallbackIterator::CallbackIterator() : m_state(STATE_COMPLETE), m_diveIndex(0), m_target(0), m_event(0) { };
 
-  Layout::CallbackIterator::CallbackIterator(Layout *target, const VerbBase *event) : m_state(STATE_DIVE), m_diveIndex(0), m_target(target), m_event(event) { // set to STATE_DIVE so that NextIndex() does the right thing
+  Layout::CallbackIterator::CallbackIterator(Layout *target, const VerbGeneric *event) : m_state(STATE_DIVE), m_diveIndex(0), m_target(target), m_event(event) { // set to STATE_DIVE so that NextIndex() does the right thing
     if (event->DiveGet()) {
       // Dive event! Accumulate everything we need
       Layout *ctar = target;
@@ -1174,7 +1174,7 @@ namespace Frames {
         layout = m_dives[m_diveIndex];
       }
 
-      const VerbBase *event = m_event;
+      const VerbGeneric *event = m_event;
       if (m_state == STATE_DIVE) {
         event = event->DiveGet();
       } else if (m_state == STATE_BUBBLE) {
@@ -1210,7 +1210,7 @@ namespace Frames {
       }
 
       Layout *layout = LayoutGet();
-      const VerbBase *event = VerbGet();
+      const VerbGeneric *event = VerbGet();
 
       // TODO: can probably be optimized by not doing a ton of lookups
       if (layout->m_events.count(event)) {
@@ -1230,7 +1230,7 @@ namespace Frames {
     }
   }
 
-  const VerbBase *Layout::CallbackIterator::VerbGet() {
+  const VerbGeneric *Layout::CallbackIterator::VerbGet() {
     if (m_state == STATE_DIVE) {
       return m_event->DiveGet();
     } else if (m_state == STATE_BUBBLE) {