koffice/chalk/doc/DESIGN.obsolete

A Perspective on Chalk's Design

  Chalk's codebase has been through as many changes as the app's name
  itself. It started with KImageShop (hence the 'kis' prefix one finds
  everwhere, and which would have been unnessary had Chalk used
  namespaces, one fancies), then became Krayon to end up as Chalk. The
  stated design goal was to create a application geared towards the
  more artistic user; the kind of user who settles down with his
  tablet to create a spot of Art. It ended up as a Gimp-clone, a Kimp,
  so to say.

  This document was the basis for a discussion on the chalk mailinglist:
  http://lists.kde.org/?l=kde-kimageshop&m=106530035202770&w=2. See the
  answer for some answers to the questions at the end.
  
Design Patterns

  Patrick Julien restructured Chalk to use a lot design patterns. Chalk
  appears to have a very solid base for blasting pixels to the screen,
  zooming, selecting and moving. These are what I recognize as his
  changes:

            * Change brushes handling to a generic Mediator pattern
              (kis_resource_mediator). Resources are brush shapes,
              patterns (and colours, too?) Patrick intended a Flyweight
              here.

            * The composite pattern is used in paint devices, layers, channels,
              etc. (What about masks?)

            * Change colourspace handling to a Strategy pattern
              (strategy/kis_strategy_color)

            * Change moving chunks of painting to a Strategy pattern
              (strategy/kis_strategy_move)

            * kis_factory points towards a Factory pattern Creates the 
              pluginserver and resourceserver.

            * Tools are created by a Factory pattern (but it isn't
              dynamic yet): kis_tool_factory. Tools are intended to
              become tdeparts.

            * There's the start of a Memento pattern for tools, but it
              doesn't seem to be used (kis_tool_memento). It was an 
              experiment that didn't pan out.

            * The Builder pattern is used to do conversion to and/or
              from ImageMagick. I guess this is used for importing
              images in other file-formats than .chalk. An idea at one
              was to use Koffice filters, but that didn't work because
              images are rather different from other office documents.

            * Flyweight pattern used for background tiles.
              kis_background.

            * Nameserver. Perhaps not a pattern -- at least not one
              with an obvious GOF name. Appears to be computing a
              number for new layers and new documents.

            * kis_render. Interface implemented by kis_paint_device
              and kis_image.

            * Rename kisTool to kisToolInterface -- but the file is
              still called kis_tool. (This is intentional, and should
              be kept in the style guide.)

            * Addition of kis_types. Defines shared pointer pointers
              to core chalk objects: image, paintdevice, channel,
              mask, layer etc.
             
            * Tile architecture. There's Mediator and a Singleton
              pattern here at least. This stuff seems to work, doesn't
              need hacking at the moment.
              
            * Visitor pattern used to flatten an image or merge 
              layers. Merging exposes a funny bug where the tiles
              are re-arranged in an interesting mosaic pattern.


User interface

  Chalk uses a fairly ugly side-panel to collect what are palettes
  in other applications. I would prefer dockable, attachable
  palettes myself. Doesn't KDE have a lib for that already?


  ui/labels

        These classes are used in the statusbar.

  ui

        The dialogs appear to be created by hand, not with Qt
        Designer. Besides, many are inoperational.
        
  other

        The canvas, rules and sidebar panels are defined here, too,
        nicely separated.

Tools

  Working: select_rectangular, test, zoom, colorpicker, paste, move

  Not working: airbrush, brush, colorchanger (no idea what it should
  do), ellipse, eraser, fill, line, pen, polygon, polyline, 
  rectangle, select_contiguous, select_elliptical, select_freehand,
  select_polygonal, stamp

  Missing tools: convolve, smear, smudge, whirl, charcoal, chalk,
  oils, clone, select_by_colour

Plugins

  The single plugin example has been present in chalk since about day
  one, as far as I can see. It doesn't show anything about what one
  can do with plugins.

  To judge from the code in kis_plugin_server, it never got beyond
  an idea. (kdDebug() << "hallo\n"...)

  (This code should be removed.)

ImageMagick

  There still appear to be some dependencies upon ImageMagick (builder
  subdir). What are these for, and should they stay? Is it for
  importing/exporting foreign file formats?

Undo/Redo

  Undo and Redo make use of the standard KDE mechanism, which I don't
  really understand either.


Obsolete files

  The following files appear to be unused:

    core/helper/kis_timer
    core/helper/kis_scopedlock (Replaced with QMutexlocker)
    core/kis_krayon (was predecessor of kis_resource)
    core/kis_mask
    core/kis_util
    ui/kis_krayon_widget

Random head-scratchings


       - Why the QUANTUM redefinition: the number of bits per channel,
         8 for 32-bit colour, 16 for 64-bit colour.

       - is_mask unimplemented? What was it meant to do, or is it an
       interface?

       - nameserver presents unique numbers for new layers and images.

       - what does 'upscale' do?  in 8 bit/channel color mode, upscale
         doesn't do anything.  However, downscale and upscale in > 8 bit,
         this is needed to covert the color for the actual display 
         rendering, i.e. X, etc, only do 8 bit color. Using this 
         everywhere you work on color will keep chalk color channel
         bit depth independent.


       - Is KisVector only used in obsolete tools?

       - I take it that the two tests that are present in chalk/test
       are obsolete?

       - what with the dummmmmy.cc?

       - which bits of the chalk/ui files are still relevant?

       - kis_selection.h needs to be included to compile code that
         uses kis_paint_device, and I wonder why.

       - what is paint-offset?