Commit 59472669 authored by Nils Philippsen's avatar Nils Philippsen

devel-docs: rewording, grammar fixes, etc.

parent 17ca1ea1
......@@ -3,10 +3,11 @@ Developers documentation
This directory holds information that you will find useful if you
develop a GIMP plug-in or want to work on the GIMP core.
See http://wiki.gimp.org/index.php/Main_Page for more.
See http://wiki.gimp.org/index.php/Main_Page for more information.
app - setup for documentation of the GIMP core;
not build by default since it is huge and
not built by default since it is huge and
only relevant for core developers
libgimp
......@@ -28,7 +29,7 @@ See http://wiki.gimp.org/index.php/Main_Page for more.
uses milestones in the Bugzilla bugtracker
commit-rules.txt - describes rules and things to think
about when creating GIMP commits
contexts.txt - describes how the GimpContext's in GIMP are used
contexts.txt - describes how GimpContexts are used in GIMP
debug-plug-ins.txt - how to debug GIMP plug-ins
exif-handling.txt - how GIMP should handle EXIF data
includes.txt - the policy for inclusion of header files
......@@ -36,7 +37,7 @@ See http://wiki.gimp.org/index.php/Main_Page for more.
release-howto.txt - a check-list for doing a GIMP release
submitting-patches.txt - how to submit a patch for GIMP
tagging.txt - how resource tagging in Gimp works
ui-framework.txt - describes the GIMP UI framework functions and
ui-framework.txt - describes how the GIMP UI framework functions and
how it is implemented
undo.txt - description of the undo system
......@@ -46,9 +47,9 @@ See http://wiki.gimp.org/index.php/Main_Page for more.
also check out gimp-module-dependencies.svg
gbr.txt - description of the GBR format used to store a
gbr.txt - description of the GBR format used to store
pixmap brushes
ggr.txt - description of the GGR format used to store a
ggr.txt - description of the GGR format used to store
GIMP gradients
gih.txt - description of the GIH format used to store a
series of pixmap brushes
......
......@@ -9,8 +9,8 @@ https://bugzilla.gnome.org/browse.cgi?product=GIMP.
Stable milestone
----------------
The bugs on the stable milestone, i.e. on the 2.6 milestone if GIMP
2.6 is the stable release, are bugs for which fixes will be accepted
The bugs on a stable milestone, e.g. on the 2.8 milestone if GIMP
2.8 is the stable release, are bugs for which fixes will be accepted
onto the stable branch.
Reports for bugs that are fixed in the stable branch should have the
......@@ -21,8 +21,8 @@ branch and then cherry-picked to the stable branch.
Next stable milestone
---------------------
The bugs/enhancement requests on the next stable milestone, i.e. on
the 2.8 milestone if GIMP 2.6 is the stable release, are bugs or
The bugs/enhancement requests on the next stable milestone, e.g. on
the 2.10 milestone if GIMP 2.8 is the stable release, are bugs or
enhancement requests scheduled and planned for inclusion in the next
stable version. This list is rather dynamic and will be altered during
the execution of a development cycle.
......
......@@ -4,7 +4,7 @@ contexts.txt
Introduction
------------
This file describes how the GimpContext's in GIMP are used.
This file describes how GimpContexts are used in GIMP.
Overview
......@@ -21,7 +21,7 @@ also have their own context.
Communication between contexts
------------------------------
So how does the various contexts synchronize and propagate changes?
So how do the various contexts synchronize and propagate changes?
This is most easily explained by a sequence diagram. Let's say there
are two image windows with different images opened in GIMP. Call them
A and B. Let's say A is currently active. When the user activates B,
......@@ -54,9 +54,9 @@ events is as follows:
| | | |------------>|
| | | | |
In single-window mode, the dockables listens directly to the user
In single-window mode, the dockables listen directly to the user
context. When switching between single-window and multi-window modes,
the dockables are updated with their new context. Just as when moving
the dockables are updated with their new context, just as when moving
a dockable between different dock windows and thus also different
contexts. The sequence diagram for single-window mode is:
......
gtkbuilder-porting-guide.txt
============================
This document describes some tips and rules for how to port UI code
This document describes some tips and rules for porting UI code
written with GTK+ and C to GtkBuilder + Glade.
......
=============================================================
How resource tagging in Gimp works?
How does resource tagging in Gimp work?
=============================================================
GimpTagged
Tagging is not limited to a concrete class hierarchy, but any class
implementing GimpTagged interface can be tagged. In addition to
implementing the GimpTagged interface can be tagged. In addition to
methods for adding/removing/enumerating tags it also requires
GimpTagged objects to identify themselves:
* gimp_tagged_get_identifier: used to get a unique identifier of
* gimp_tagged_get_identifier: used to get a unique identifier of a
GimpTagged object. For objects which are stored in a file it will
usually be a filename.
* gimp_tagged_get_checksum: identifier mentioned above has a problem
* gimp_tagged_get_checksum: the identifier mentioned above has the problem
that it can change during sessions (for example, user moves or renames
a resource file). Therefore, there needs to be a way to get other
identifier from data of the tagged object, so that tags stored between
session could be properly remapped.
a resource file). Therefore, there needs to be a way to get another
identifier from the data of the tagged object, so that tags stored between
session can be remapped properly.
GimpTag
Tags are represented by GimpTag object. There are no limitations for
tags names except they cannot contain a selected set of terminal
punctuations characters (used to separate tags), no whitespace at the
end or front and cannot begin with a reserved prefix for internal tags
('gimp:'). These conditions are ensured when creating tag object from
tag string. The only reason for tag creation to fail is when there are
no characters left after applying trying to fix a tag according to the
rules above. Tag names are displayed as user typed them (case
sensitive), but tag comparing is done case insensitively.
Tags are represented by a GimpTag object. There are no limitations for
tag names except that they cannot contain a selected set of terminal
punctuation characters (used to separate tags), leading or trailing
whitespace and cannot begin with a reserved prefix for internal tags
('gimp:'). These conditions are enforced when creating a tag object from a
tag string. The only reason for tag creation to fail is if there are
no characters left after trying to fix a tag according to the
rules above. Tag names are displayed as the user typed them (case
sensitive), but tag comparison is done case-insensitively.
Tags are immutable, ie. when tag is created with one name string, it
cannot be changed, but new tag has to be created instead.
Tags are immutable, i.e. when a tag is created with one name string, it
cannot be changed, but a new tag has to be created instead.
There are methods provided for convenient use with GLib: compare
function which can be used to sort tag list and functions for storing
tags in GHashTable.
There are methods provided for convenient use with glib, a comparison
function which can be used to sort tag lists and functions for storing
tags in a GHashTable.
GimpTagCache
Between sessions tags assigned to objects are stored in a cache
file. Cache file is a simple XML file, which lists all resources and
Between sessions, tags assigned to objects are stored in a cache
file. The cache file is a simple XML file, which lists all resources and
tags which are added to them. Resources which have no tags assigned
are listed here too, so that when we check the cache we know that they
have no tags assigned instead trying to find out if the resource file
have no tags assigned instead of trying to find out if the resource file
has been renamed.
When session ends, list or all resources and tags they have assigned
When the session ends, a list of all resources and their tags
is constructed. Resources which were not loaded during this session,
but had tags assigned are also added to the list (they are saved
because they could be useful in the next session, for example, when
temporarily disconnected network directory is reconnected). The list
is then written to a tag cache file in user home directory.
a temporarily disconnected network directory is reconnected). The list
is then written to a tag cache file in the user's home directory.
When session starts, previously saved resource and tag mapping has to
be loaded and assigned to GimpTagged objects. First tag cache is
When the session starts, the previously saved resource and tag mapping has to
be loaded and assigned to GimpTagged objects. First the tag cache is
loaded from file, and then containers are added (GimpContainer objects
where contained items implement GimpTagged interface). After that,
which contain items implementing the GimpTagged interface). After that,
loaded resources are assigned tags:
If resource identifier matches identifier in cache,
corresponding tags are assigned to GimpTagged object.
Else, if the identifier is not found in tag cache,
attempt is made to check if resource file has been
moved/renamed. In such case checksum is used to match the
GimpTagged object with all of the records in tag cache.
If match is found,
identifier is updated in tag cache.
If a resource identifier matches an identifier in the cache,
corresponding tags are assigned to the GimpTagged object.
Else, if the identifier is not found in the tag cache,
an attempt is made to check if the resource file has been
moved/renamed. In such case the checksum is used to match the
GimpTagged object with all of the records in the tag cache.
If a match is found,
the identifier is updated in the tag cache.
Otherwise,
loaded GimpTagged object is considered to be a newly
the loaded GimpTagged object is considered to be a newly
added resource.
GimpFilteredContainer
GimpFilteredContainer is a "view" (representation) of
GimpContainer. What relates it to tagging, is that it can be used to
filter GimpContainer to contain only GimpTagged objects which have
A GimpFilteredContainer is a "view" (representation) of a
GimpContainer. It is related to tagging in that it can be used to
filter a GimpContainer to contain only GimpTagged objects which have
certain tags assigned. It is automatically updated with any changes in
GimpContainer it wraps. However, items should not be added or removed
from this container manually as changes do not affect original
container and would be lost when GimpFilteredContainer is
updated. Instead, the contents should be changed by setting tag list
the GimpContainer it wraps. However, items should not be added or removed
from this container manually as changes do not affect the original
container and would be lost when the GimpFilteredContainer is
updated. Instead, the contents should be changed by setting a tag list
which would be used to filter GimpTagged objects containing all of the
given GimpTags.
GimpFilteredContainer can use any GimpContainer as source
container. Therefore, it is possible to use decorator design pattern
to implement additional container views, such as view combining items
GimpFilteredContainer can use any GimpContainer as a source
container. Therefore, it is possible to use the decorator design pattern
to implement additional container views, such as a view combining items
from multiple containers.
GimpTagEntry widget
GimpTagEntry widget extends GtkEntry and is used to either assign or
query tags depending on selected mode. The widget support various
The GimpTagEntry widget extends GtkEntry and is used to either assign or
query tags depending on the selected mode. The widget support various
usability features:
* jellybeans. When tag is entered and confirmed by either separator,
* Jellybeans: When a tag is entered and confirmed by either separator,
pressing return or otherwise, it becomes a jellybean, i.e. a single
unit, not a bunch of characters. Navigating in GimpTagEntry,
deleting tags, etc can be performed much quicker. However, when tag
unit, not a bunch of characters. Navigating in a GimpTagEntry,
deleting tags, etc. can be performed much faster. However, while a tag
is just being entered (not yet confirmed), all actions operate on
characters as usual.
* custom auto completion is implemented in GimpTagEntry widget which
allows to complete tags in the middle of tag list, doesn't offer
* Custom auto completion is implemented in the GimpTagEntry widget which
allows to complete tags in the middle of a tag list, doesn't offer
already completed tags, tab cycles all possible completions, etc.
* when GimpTagEntry is empty and unused it displays description for
user regarding it's purpose.
* If the GimpTagEntry is empty and unused it displays a description for
the user regarding its purpose.
When operating in tag assignment mode, tags are assigned only when
user hits return key.
the user hits the return key.
When operating in tag query mode, given GimpFilteredContainer is
filtered as user types. GimpTagEntry also remembers recently used
When operating in tag query mode, the given GimpFilteredContainer is
filtered as the user types. The GimpTagEntry also remembers recently used
configurations, which can be cycled using up and down arrow keys.
GimpComboTagEntry widget
GimpComboTagEntry widget extends GimpTagEntry and adds ability to pick
tags from a menu like list (GimpTagPopup widget).
The GimpComboTagEntry widget extends GimpTagEntry and adds the ability to pick
tags from a menu-like list (using the GimpTagPopup widget).
GimpTagPopup widget
GimpTagPopup widget is used as a tag list menu from GimpComboTagEntry
The GimpTagPopup widget is used as a tag list menu from the GimpComboTagEntry
widget. It is not designed to be used with any other widget.
GimpTagPopup has many visual and behavioral similarities to GtkMenu.
......@@ -139,10 +139,10 @@ In particular, it uses menu-like scrolling.
GimpTagPopup implements various usability features, some of which are:
* tags which would result in empty selection of resource are made
* Tags which would result in an empty selection of resources are made
insensitive.
* closing with either keyboard or pressing outside the popup area.
* Closing either with the keyboard or by clicking outside the popup area.
* underline highlighted (hovered) tags.
* Underlining of highlighted (hovered) tags.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment