1 /*
2 * This file is a part of CAST project.
3 * (c) Copyright 2007, AGH University of Science & Technology
4 * https://caribou.iisg.agh.edu.pl/trac/cast
5 *
6 * Licensed under the Eclipse Public License, Version 1.0 (the "License").
7 * You may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 * http://www.eclipse.org/legal/epl-v10.html
10 */
11 /*
12 * File: IVisualResource.java
13 * Created: 2009-07-17
14 * Author: kpietak
15 * $Id$
16 */
17
18 package pl.edu.agh.cast.resource;
19
20 import java.util.List;
21
22 import org.eclipse.swt.graphics.Image;
23
24 import pl.edu.agh.cast.data.model.Type;
25
26 /**
27 * An interface representing single visual resource which contains of:
28 * <ul>
29 * <li>unique string identifier (not null and not empty),
30 * <li>localized label (not null),
31 * <li>localized description (not null),
32 * <li>images (icons).
33 * </ul>
34 * A single resource can have many images which differ in the following things:
35 * <ul>
36 * <li>size described by {@link ImageSize},
37 * <li>variants described by predefined string constants. A image variant allows for defining additional images
38 * describing different states of elements associated with the visual resource. For example, an action icon resource can
39 * define additional icons for disabled status; a folder resource can contain open, close, full, etc variants of images.
40 * Predefined constants are in {@link ImageVariants}, although one can extend the constant list.
41 * </ul>
42 *
43 * @author AGH CAST Team
44 */
45 public interface IVisualResource {
46
47 /**
48 * A character used to separate parts of image name such as size, variant and right name.
49 */
50 public static final char NAME_SEPARATOR = '_';
51
52 /**
53 * Gets resource id. For resources representing type such as phone number, entity, etc the id should be equal to
54 * {@link Type#toString()}. In other cases the id should be unique string in Java package style.
55 *
56 * @return resource id
57 */
58 public String getId();
59
60 /**
61 * Returns tags associated with the resource.
62 *
63 * @return list of tags
64 */
65 public List<String> getTags();
66
67 /**
68 * Returns group id.
69 *
70 * @return group id or <code>null</code> if the resource has no group.
71 */
72 public String getGroupId();
73
74 /**
75 * Returns type of element represented by the resource.
76 *
77 * @return element or data set type or <code>null</code> if the resource is not associated with any element
78 */
79 public Type getType();
80
81 /**
82 * Gets localized resource label.
83 *
84 * @return resource label
85 */
86 public String getLabel();
87
88 /**
89 * Gets localized resource description.
90 *
91 * @return resource description
92 */
93 public String getDescription();
94
95 /**
96 * Gets default image associated with the resource. If the default image has only one size registered this version
97 * is returned, otherwise the default size (according to {@link ImageSize#getDefaultSize()} is searched and
98 * returned, if not found <code>null</code> is returned
99 *
100 * @return default image, <code>null</code> if image not exists
101 */
102 public Image getImage();
103
104 /**
105 * Gets default image associated with this resource with specified size.
106 *
107 * @param size
108 * image size
109 * @return image with specified size, <code>null</code> if image not exists
110 */
111 public Image getImage(ImageSize size);
112
113 /**
114 * Gets a given variant of image in default size (see {@link #getImage()} method java doc for more details about how
115 * default size is chosen).
116 *
117 * @param variant
118 * image variant
119 * @return a specified variant of the resource image, <code>null</code> if variant of image not exists
120 */
121 public Image getImage(String variant);
122
123 /**
124 * Gets a given variant of image in specified size.
125 *
126 * @param variant
127 * image variant
128 * @param size
129 * image size
130 * @return a specified variant of the resource image, <code>null</code> if image not exists
131 */
132 public Image getImage(String variant, ImageSize size);
133
134 /**
135 * Disposes the resource. It disposes all hold images.
136 */
137 public void dispose();
138
139 }