%ModuleHeaderCode // fix to allow compilation with sip 4.7 #include #include #include %End /** * \ingroup composer * \class QgsComposerMultiFrame * Abstract base class for composer items with the ability to distribute the content to several frames * (QgsComposerFrame items). */ class QgsComposerMultiFrame: QgsComposerObject { %TypeHeaderCode #include %End %ConvertToSubClassCode if (dynamic_cast(sipCpp) != NULL) sipType = sipType_QgsComposerHtml; else if (dynamic_cast(sipCpp) != NULL) sipType = sipType_QgsComposerAttributeTableV2; else if (dynamic_cast(sipCpp) != NULL) sipType = sipType_QgsComposerTableV2; else if (dynamic_cast(sipCpp) != NULL) sipType = sipType_QgsComposerMultiFrame; else sipType = NULL; %End public: /** Specifies the behavior for creating new frames to fit the multiframe's content */ enum ResizeMode { UseExistingFrames, /*!< don't automatically create new frames, just use existing frames */ ExtendToNextPage, /*!< creates new full page frames on the following page(s) until the entire multiframe content is visible */ RepeatOnEveryPage, /*!< repeats the same frame on every page */ RepeatUntilFinished /*!< creates new frames with the same position and dimensions as the existing frame on the following page(s), until the entire multiframe content is visible */ }; /** Construct a new multiframe item. * @param c parent composition * @param createUndoCommands */ QgsComposerMultiFrame( QgsComposition *c /TransferThis/, bool createUndoCommands ); virtual ~QgsComposerMultiFrame(); /** Returns the total size of the multiframe's content. * @returns total size required for content */ virtual QSizeF totalSize() const = 0; /** Returns the fixed size for a frame, if desired. If the fixed frame size changes, * the sizes of all frames can be recalculated by calling recalculateFrameRects(). * @param frameIndex frame number * @returns fixed size for frame. If the size has a width or height of 0, then * the frame size is not fixed in that direction and frames can have variable width * or height accordingly. * @note added in version 2.5 * @see minFrameSize * @see recalculateFrameRects */ virtual QSizeF fixedFrameSize( const int frameIndex = -1 ) const; /** Returns the minimum size for a frames, if desired. If the minimum * size changes, the sizes of all frames can be recalculated by calling * recalculateFrameRects(). * @param frameIndex frame number * @returns minimum size for frame. If the size has a width or height of 0, then * the frame size has no minimum in that direction. * @note added in version 2.5 * @see fixedFrameSize * @see recalculateFrameRects */ virtual QSizeF minFrameSize( const int frameIndex = -1 ) const; /** Renders a portion of the multiframe's content into a painter. * @param painter destination painter * @param renderExtent visible extent of content to render into the painter. * @param frameIndex frame number for content * @note added in version 2.5 */ virtual void render( QPainter *painter, const QRectF &renderExtent, const int frameIndex ) = 0; /** Adds a frame to the multiframe. * @param frame frame to add * @param recalcFrameSizes set to true to force recalculation of all existing frame sizes * @see removeFrame */ virtual void addFrame( QgsComposerFrame *frame /Transfer/, bool recalcFrameSizes = true ) = 0; /** Finds the optimal position to break a frame at. * @param yPos maximum vertical position for break * @returns the optimal breakable position which occurs in the multi frame close * to and before the specified yPos * @note added in version 2.3 */ virtual double findNearbyPageBreak( double yPos ); /** Removes a frame from the multiframe. This method automatically removes the frame from the * composition. * @param i index of frame to remove * @param removeEmptyPages set to true to remove pages which are empty after the frame is removed * @see addFrame * @see deleteFrames */ void removeFrame( int i, const bool removeEmptyPages = false ); /** Removes and deletes all child frames. * @see removeFrame */ void deleteFrames(); /** Sets the resize mode for the multiframe, and recalculates frame sizes to match. * @param mode resize mode * @see resizeMode */ void setResizeMode( ResizeMode mode ); /** Returns the resize mode for the multiframe. * @returns resize mode * @see setResizeMode */ ResizeMode resizeMode() const; /** Stores state information about multiframe in DOM element. Implementations of writeXML * should also call the _writeXML method to save general multiframe properties. * @param elem is DOM element * @param doc is the DOM document * @param ignoreFrames set to false to avoid writing state information about child frames into DOM * @see _writeXML */ virtual bool writeXml( QDomElement &elem, QDomDocument &doc, bool ignoreFrames = false ) const = 0; /** Stores state information about base multiframe object in DOM element. Implementations of writeXML * should call this method. * @param elem is DOM element * @param doc is the DOM document * @param ignoreFrames set to false to avoid writing state information about child frames into DOM * @see writeXML */ bool _writeXml( QDomElement &elem, QDomDocument &doc, bool ignoreFrames = false ) const; /** Reads multiframe state information from a DOM element. Implementations of readXML * should also call the _readXML method to restore general multiframe properties. * @param itemElem is DOM element * @param doc is the DOM document * @param ignoreFrames set to false to avoid read state information about child frames from DOM * @see _readXML */ virtual bool readXml( const QDomElement &itemElem, const QDomDocument &doc, bool ignoreFrames = false ) = 0; /** Restores state information about base multiframe object from a DOM element. Implementations of readXML * should call this method. * @param itemElem is DOM element * @param doc is the DOM document * @param ignoreFrames set to false to avoid reading state information about child frames from DOM * @see readXML */ bool _readXml( const QDomElement &itemElem, const QDomDocument &doc, bool ignoreFrames = false ); /** Returns the parent composition for the multiframe. * @returns composition */ QgsComposition *composition(); /** Returns whether undo commands should be created for interactions with the multiframe. * @returns true if undo commands should be created * @see setCreateUndoCommands */ bool createUndoCommands() const; /** Sets whether undo commands should be created for interactions with the multiframe. * @param enabled set to true if undo commands should be created * @see createUndoCommands */ void setCreateUndoCommands( bool enabled ); /** Returns the number of frames associated with this multiframe. * @returns number of child frames **/ int frameCount() const; /** Returns a child frame from the multiframe. * @param i index of frame * @returns child frame if found * @see frameIndex */ QgsComposerFrame *frame( int i ); /** Returns the index of a frame within the multiframe * @param frame frame to find index of * @returns index for frame if found, -1 if frame not found in multiframe * @note added in version 2.5 * @see frame */ int frameIndex( QgsComposerFrame *frame ) const; /** Creates a new frame and adds it to the multi frame and composition. * @param currentFrame an existing QgsComposerFrame from which to copy the size * and general frame properties (e.g., frame style, background, rendering settings). * @param pos position of top-left corner of the new frame * @param size size of the new frame * @returns new QgsComposerFrame * @note added in version 2.3 */ QgsComposerFrame *createNewFrame( QgsComposerFrame *currentFrame, QPointF pos, QSizeF size ); /** Get multiframe display name. * @returns display name for item * @note added in version 2.5 */ virtual QString displayName() const; public slots: /** Forces a redraw of all child frames. */ void update(); /** Recalculates the portion of the multiframe item which is shown in each of it's * component frames. If the resize mode is set to anything but UseExistingFrames then * this may cause new frames to be added or frames to be removed, in order to fit * the current size of the multiframe's content. * @see recalculateFrameRects */ virtual void recalculateFrameSizes(); /** Forces a recalculation of all the associated frame's scene rectangles. This * method is useful for multiframes which implement a minFrameSize() or * fixedFrameSize() method. * @note added in version 2.5 * @see minFrameSize() * @see fixedFrameSize() * @see recalculateFrameSizes */ void recalculateFrameRects(); signals: /** Emitted when the properties of a multi frame have changed, and the GUI item widget * must be updated. */ void changed(); /** Emitted when the contents of the multi frame have changed and the frames * must be redrawn. */ void contentsChanged(); protected slots: /** Called before a frame is going to be removed. Updates frame list and recalculates * content of remaining frames. */ void handleFrameRemoval( QgsComposerItem *item ); /** Adapts to changed number of composition pages if resize type is RepeatOnEveryPage. */ void handlePageChange(); };