[scribus-dev] Some notes/questions about Scribus internals and my project

[Elvis Stansvik]

Hi Andreas,

2011/5/23 Andreas Vox <avox at arcor.de>:
> Hi Elvis!
>
> Good observations for the most part. Some comments inline:
>
> ...
>
> There may be different documents, but we only have one UndoAction linked to
> the UI.
> So at one point we need to decide which document to use anyway.

I see. Makes sense.

>> Also, even though it is a
>> singleton, pointers to the undo manager still seems to be kept in
>> classes such as ScribusView and ScribusMainWindow. But I guess this is
>> just for convenience?
>
> I guess you are right (for some given value of "convenience"). Feel free to
> use the singleton instead.

Okay.

>> General Notes
>> -------------------
>> Many of the classes such as ScribusDoc, ScribusView and PageItem have
>> a huge number of public member variables, many of them undocumented,
>> which users (and subclasses) of the classes rely on, and it's a bit
>> hard to tell what the responsibilities of each class really is. But I
>> think I have a somewhat OK view of it now.
>
> Yes, isn't that ugly? :-) It's on the roadmap for refactoring.

Well I didn't want to be the one to say it, but yes ;) Good to hear
that a refactor is on the map. Anyway, it's completely understandable
for a large code base to grow some warts over time.

>> CanvasMode
>> -----------------
>> Different modes of operations on the canvas seems to be implemented in
>> classes inheriting from CanvasMode. As an example, there is a canvas
>> mode for editing a polygon, editing a spiral et.c.
>>
>> At a even higher level there seems to be the concept of "application
>> modes" (e.g. ScribusMainWindow::setAppMode(int)), which I'm not quite
>> sure what they are. Are they the same as canvas modes? In any case,
>> setting the "app mode" using ScribusMainWindow::setAppMode(int) seems
>> to be what results in a canvas mode change.
>
> In the beginning Scribus just had application modes and some huge switches
> and
> if-then-else constructs to do the right thing at the right time. I
> refactored
> all that code into CanvasModes (correspond to application modes) and
> CanvasGestures
> (correspond to submodes, ie. Scribus returns to the CanvasMode it was in
> before the
> CanvasGesture was started. Gestures could be stacked).
>
> This structure made it possible to concentrate on a single user interaction
> when
> implementing mouse event code.

Yes, I got the feeling that the canvas mode was a solution to an
earlier problem. Thanks for clarifying.

>> Notes on Painting of Items
>> -----------------------------------
>> Painting seems to be done in two places. The on-canvas painting of
>> items seems to be done by items themselves in their DrawObj_Item()
>> (and DrawObj_Decoration()) method. Painting of items for print output
>> seems to be done in the respective drawItem_*() methods in
>> ScPageOutput.
>
> IIRC ScPageOutput is only used for printing in Scribus. There's additional
> code
> in pdflib_core.cpp and pslib.cpp (Yes, 4 versions of the same code. That's
> another refactoring on the roadmap!)

Yikes. But OK, just guess we'll have to deal with that.

>> Now on to more specifics regarding my project. Below is a rough plan
>> for the first two weeks.
>>
>> Week 1 - Prototype
>> ------------------------
>> Begin creating a first basic PageItem_Table that has the traditional
>> basic table API. Something like (preliminary):
>>
>> public:
>>   qreal width() const;
>>   qreal height() const;
>>
>>   int rows () const;
>>   int columns () const;
>>
>>   void insertRows(int index, int rows);
>>   void removeRows(int index, int rows);
>>   QList<qreal> &rowHeights() const;
>>   void setRowHeights(const QList<qreal> &rowHeights);
>>
>>   void insertColumns(int index, int columns);
>>   void removeColumns(int index, int columns);
>>   QList<qreal> &columnWidths() const;
>>   void setColumnWidths(const QList<qreal> &columnWidths);
>>
>>   void mergeCells(int row, int column, int numRows, int numCols);
>>   void splitCell(int row, int column, int numRows, int numCols);
>>
>> private:
>>   /// Returns rectangle available for cell content.
>>   QRectF cellContentRect(int row, int column) const;
>>
>
> I don't see any API to acces the content of a cell?

See further down: "The table will not support any content yet, [...]".
This is for the first week. Baby steps you know. But of course there
will be an API for querying the content of the table, once it's
available, and also a lot of other API that isn't in the above list.

That said, I've already implemented large parts of the API above, so
maybe the schedule will have to be revised :)

>> ...
>>
>> Specific Questions
>> ------------------------
>> 1) Since painting of items is done in two places, in the
>> DrawObj_Item() method of the item itself and in ScPageOutput, does
>> this mean I'll have to write the painting code twice?
>
> Or 4 times, see above. We'll have to discuss that (maybe find a way to
> reuse existing text code or maybe we can do the refactoring earlier so
> that DrawObj_Item(ScPainter) is enough).

Yes, I naturally welcome any solutions that makes me not have to write
essentially the same painting code 4 times, but we'll discuss that
later. The painting code will grow over time, and at this early stage
I'll stick do doing it in DrawObj_Item method.

>> 2) How does the current undo/redo system work? How do I implement
>> undoable actions? Will I need to implement one (or several?) new
>> UndoState classes?
>
> Yes, that's what I'd recommend. See my other post.

Okay.

Thanks for your reply Andreas.

Regards,
Elvis