mirror of https://github.com/GNOME/gimp.git
devel-docs: rewording, grammar fixes, etc.
This commit is contained in:
Nils Philippsen
parent
17ca1ea170
commit
594726698f
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
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.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,137 +1,137 @@
|
|||
=============================================================
|
||||
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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue