diff --git a/rsd.tree b/rsd.tree index d94f01d..a9c476e 100644 --- a/rsd.tree +++ b/rsd.tree @@ -512,16 +512,9 @@ - - - - @@ -540,11 +533,8 @@ - - CurrentIconTheme { get; } - ThemedIconManagerIcons Icons { get; } - IThemedIconManagerRawApi GetRawApi(); -} -``` - -The `CurrentIconTheme` property will return an observable property that contains the current icon theme, which can be retrieved for inspection, or subscribed to, in order to know when a theme has changed. See the [icon theming section](Theming_Icons.md) for more details on `IconTheme`. - -The `GetRawApi` method is intended for internal use. - -The Icons property returns an instance of `ThemedIconManagerIcons`, which can be used to get `ThemedIconLoader`, which in turn is responsible for loading and caching images. - -```csharp -var loader = manager.Icons[myIconId]; -``` - -Once you have a `ThemedIconLoader`, the following properties will retrieve a bitmap and `ImageSource`, either based on the current theme, or as a live, observable property that updates when the theme changes. - -* **`CurrentGdipBitmapScreenDpi`** returns a `System.Drawing.Bitmap` of the icon for the current theme, for use in Windows Forms. The icon is rendered at the current screen DPI, so will work correctly in high DPI scenarios. It is recommended over the `CurrentGdipBitmap96` property, which renders the icon at 96 DPI, which will not look good in high DPI. -* **`LiveGdiBitmapScreenDpi`** returns an observable `IProperty` which will notify of new values when the theme changes. The bitmap is rendered at the screen DPI and should be favoured over `LiveGdipBitmap96` which is only rendered at 96 DPI, and will not look good in high DPI. -* **`CurrentImageSource`** returns a WPF `ImageSource` of the icon for the current theme. This can be a vector image, or a bitmap that will be correctly rendered when used in a WPF window. -* **`LiveImageSource`** returns an observable `IProperty` which will update whenever the image changes, due to theme changes. - -## WPF controls - -The `ThemedIconViewImage` class is a WPF element that derives from `Image`, and can be used as a drop in replacement. It will set up a live binding from an icon ID to the `Source` property. If the icon ID changes, or if the icon represented by the ID changes (due to a theme change), the binding automatically updates the `Source` property and the new image is displayed. - -The icon ID can be specified either in the constructor, or by setting the `IconId` property. Alternatively, the icon ID can be bound against the `DataContext` property, allowing for automatic updates: - -```csharp -public UIElement GetThemedIconViewImage(Lifetime lifetime, IProperty liveIconId) -{ - var image = new ThemedIconViewImage(); - // Wire up the live icon ID property to push the value into the DataContext, - // which in turn causes the correctly themed icon to be displayed. The - // property binding is automatically cleared when the Lifetime terminates - liveIconId.FlowInto(lifetime, image, DataContextProperty); - return image; -} -``` - -If using compiled icons, ReSharper provides the `ThemedIcon` markup extension to provide live binding to an `Image` element's `Source` property. See below for details. - -## Using compiled icons - -The most common icon type is the compiled icon, which is compiled as a resource and embedded in an assembly. Compiled icons are identified with an instance of the `CompiledIconId` type. Typically, these icon ID instances are automatically generated, and can be found as the `Id` static property of a class named after the icon, itself implemented as a nested class named after the icon group. - -For example, you can get the icon ID for the To Do Explorer option page using: - -```csharp -var iconId = TodoItemsThemedIcons.TodoOptions.Id; -``` - -It is also possible to bind a compiled icon to an image source in WPF, using the `ThemedIcon` markup extension. The extension will create a live binding, which automatically updates the image when the icon represented by the compiled icon ID changes, usually in response to a theme change. - -```xml - -``` - -Note that the parameter to the extension is the class that holds the `CompiledIconId` instance, and not the `Id` property. This is because the XAML requires a compile time value, rather than a runtime instance. - -A similar requirement is necessary when referencing an icon in an attribute, for example with `OptionsPageAttribute`: - -```csharp -[OptionsPage(PageId, "To-do items", typeof(TodoItemsThemedIcons.ToDoItemsPage))] -public class TodoItemsPage : IOptionsPage -{ - // ... -} -``` - -The `OptionsPageAttribute` class converts the `Type` to an `IconId` using the `CompiledIconClassAttribute.TryGetCompiledIconClassId` static method: - -```csharp -var iconId = CompiledIconClassAttribute.TryGetCompiledIconClassId(typeOfIcon, OnError.LogException); -``` - -Once the `IconId` is known, the standard icon loader API discussed above can be used to get a bitmap or `ImageSource`. A shortcut is to use the `GetIcon` extension method for `IThemedIconManager` to return a `ThemedIconLoader` which can be used to get the icon image. - -```csharp -IProperty liveImage = themedIconManager.GetIcon().LiveImageSource; -``` - -## Discovering compiled icons - -ReSharper ships with over 1000 compiled icons, so finding an icon to use can be tricky. A significant number of the icons are not intended to be used by extensions - they are icons for tool windows, actions or other UI elements that are not relevant to extensions. It is recommended to create your own icons where possible, but if you wish to reuse existing icons, make sure they are intended for the same purpose (for example, do not use the "unit test pass" icon to represent success in an extension). - -Should you wish to reuse existing icons, you can make use of an Internal feature that allows you to browse all of the icons registered with the `ThemedIconManager`. Start ReSharper in Internal mode, and use the ReSharper → Internal → Windows → Show Themed Icons menu option. The tool window that opens will show all available icons, either in a tile view, flat list, or grouped by owner. This grouped option is very useful, as it will group the icons by their owner - in the case of compiled icons, this will give an indication of the name of the compiled icon ID class (the name is actually the name of the "icon pack", or the XAML file that contains the definition of the icon, but that name is usually the same as, or very similar to the icon ID class name). - -When displaying as a flat or grouped list, the icons are searchable, and typing a value will filter out any icons that don't match the search text. - -## PSI symbols - -While it is possible to use the icon manager to get icons for PSI elements such as class, method or parameter, it is highly recommended to use the `PsiIconManager` class instead. See the section on [icons in the PSI](PSI_Icons.md) for more details. diff --git a/topics/Platform/Shell/Icons/CreatingCompiledIcons.md b/topics/Platform/Shell/Icons/CreatingCompiledIcons.md deleted file mode 100644 index 4fab9d3..0000000 --- a/topics/Platform/Shell/Icons/CreatingCompiledIcons.md +++ /dev/null @@ -1,82 +0,0 @@ -[//]: # (title: Creating Compiled Icons) - -The most common type of icon is the compiled icon), represented by `CompiledIconId`. These icons are embedded into assembly references at compile type, as XAML resources. - -The ReSharper SDK includes MSBuild build actions and a custom task that will generate icons from either XAML or PNG files. The custom task generates two files - a new XAML file containing a `DrawingBrush` resource for each image, and a C# file providing the `CompiledIconId` instances, and pointers to the new XAML resource dictionary. Once the files have been generated, they should both be added to the Visual Studio project. - -## Themed icons - -Themed icons are supported by including multiple images in the generated XAML file, one version for each theme aspect supported. Each image is annotated with its own name and the theme aspect that it is intended for, so themed icons will have multiple images with the same name, but different theme aspect names. - -When retrieving an icon, the aspects from the current theme are enumerated in priority order, and the first matching image for the icon is used. If there are no images that match any of the theme aspects, the fallback image is used, if available. A fallback image is an image that is created without a theme aspect. If there are no fallback images, an arbitrary themed image for the icon is used. - -See the [theming section](Theming_Icons.md) for more details about theming and theme aspects. - -## XAML icons - -XAML images are the preferred format for icons, as they scale better for larger sizes and higher screen DPI resolutions. - -The input XAML file should be a `ResourceDictionary` containing a number of `DrawingBrush` resources, all marked with an `x:Key` attribute that uniquely identifies the icon by name. The file should be added to the Visual Studio project and have its build action set to `ThemedIconsXamlV3`. - -Each brush can contain multiple individual images, one for each supported theme aspect. The images are placed horizontally, and, rather than conforming to a strict grid, the custom task will automatically discover distinct, non-overlapping images. These images are saved to the new, generated XAML file, again as a `ResourceDictionary`, with each theme image being saved as its own individual `DrawingBrush`. - -The new XAML images need to be annotated, with both the name of the icon and the name of the theme aspect it is intended for. The theme aspect is retrieved from MSBuild metadata attached to the original XAML file. The `ThemeColumns` element is used to provide a semi-colon separated list of theme aspect names, one for each image in the horizontal strip, in the same order. - -Similar metadata is required to specify how the background of an individual image is processed. The `RemoveBackgroundElement` describes this behaviour. To all intents and purposes, there is no need to configure this, other than to set the value to `True`. - -Both pieces of metadata are required, or the custom task will not process the XAML file. To add the metadata, edit the `.csproj` project file, find the element that represents the original XAML file and set it as follows: - -```xml - - Gray;GrayDark;Color - True - -``` - -The names of the theme aspects are listed in the [theming section](Theming_Icons.md). - -## PNG icons - -ReSharper also supports using PNG files as icons, although it is recommended to use XAML instead, as XAML files can scale better to larger sizes and higher screen DPI resolutions. - -In order to create an icon from a PNG file, add the file to the Visual Studio project, and set its build action to `ThemedIconPng`. The PNG file will typically be square, e.g. 16×16, although there are no restrictions to enforce this - a larger icon could be included for high DPI or simply for displaying at a larger size. - -Theming is supported by a naming convention. The theme aspect name should be placed in square brackets, e.g. `Foo[GrayDark].png`, and a separate PNG file used for each theme aspect. If a theme aspect name isn't specified, the image is treated as a fallback image when failing to find a theme specific image. - -The theme aspect names are listed in the [theming section](Theming_Icons.md). - -## Generated files - -The custom task generates two files - a new XAML file containing the processed images, and a C# file that contains the `CompiledIconId` instances. - -The filenames are based on the name of the containing folder, using the format `ThemedIcons..generated.cs` and `ThemedIcons..generated.xaml`, where `` is the name of the containing folder, minus any `Icons` suffix. E.g. the folder `BarIcons` would create files called `ThemedIcons.Bar.generated.cs` and `ThemedIcons.Bar.generated.xaml`. - -The generated XAML is a `ResourceDictionary` where each themed image is created as an individual `DrawingBrush`, annotated with the name of the icon and the theme aspect it is intended for. - -The generated C# file contains `CompiledIconId` instances used to identify and consume the icons. The generated classes are created inside a sealed class to prevent any clashes with other classes inside that namespace. Each class derives from the empty, abstract `CompiledIconClass` class and are marked with the `[CompiledIconClass]` attribute, to allow for discovery of icon XAML files at runtime. The class also declares a couple of assembly level attributes, to help with identifying and loading the icon XAML files, assigning the friendly name to the image in the XAML, and to register a XAML namespace for the icons. - -Each class has a single public static field called `Id`, which is the instance of `IconId` that you use when consuming the icon. - -```csharp -namespace Foo -{ - // Name based on the folder containing the images - Bar - public sealed class BarThemedIcons - { - // The attribute allows for discovery of the XAML. The first argument - // is the XAML pack address of the embedded XAML resource. The second - // argument is the icon index, and the third is the name - [CompiledIconClass(".../ThemedIcons.Bar.generated.xaml", 0, "Quux")] - public sealed class Quux : CompiledIconClass - { - public static IconId Id = new CompiledIconId(".../ThemedIcons.Bar.generated.xaml", 0, "Quux"); - } - } -} -``` - -Once the files have been generated for the first time, they should be added to the Visual Studio project. - -## Other useful metadata - -The custom task also recognises the `FullPath` metadata, which is useful if the icons are being linked into the Visual Studio project from another location, perhaps shared between projects. The `FullPath` metadata should be the expected full path to the output location, where the generated files will be placed. diff --git a/topics/Platform/Shell/Icons/CustomIconTypes.md b/topics/Platform/Shell/Icons/CustomIconTypes.md deleted file mode 100644 index b474ec7..0000000 --- a/topics/Platform/Shell/Icons/CustomIconTypes.md +++ /dev/null @@ -1,66 +0,0 @@ -[//]: # (title: Custom Icon Types) - -It is possible to create a custom icon type), if the existing item types do not meet requirements. For example, the image could be retrieved from the filesystem, rather than compiled into an assembly. - -To create a custom file type, you need to create a class that derives from `IconId`. This class identifies your image, and should provide enough information to be able to create an image. It should be a value type, and must override the various `Equals`, `CompareTo` and `GetHashCode` methods to be able to properly compare two instances as the same. - -Each `IconId` is associated with a class that implements `IIconIdOwner`, and is marked with the `[ShellComponent]` attribute. This class is responsible for taking the information in the `IconId` derived class and retrieving the icon. - -```csharp -public interface IIconIdOwner -{ - Type IconIdType { get; } - ImageSource TryGetImage(IconId iconid, IconTheme theme, IThemedIconManagerPerThemeCache themedIconManagerPerThemeCache, OnError onerror); -} -``` - -The `IconIdType` member should return the `Type` of the derived `IconId` that the owner handles. When trying to get an image from an `IconId`, this type is used to lookup which class can handle the icon. - -The `TryGetImage` method is called to retrieve the image. The owner class should downcast the passed icon ID to the type of `IconId` it supports, extract the information and use that to retrieve the image. It should always return something. If it can't find an image, or if an error happens, it should return `IconPlaceholder.IconPlaceholderAvalon`, which is a WPF `ImageSource` that represents a broken icon (an icon with a cross). - -In the case of an error, the class should pass any exception to the `Handle` method on the `onerror` parameter, and return the placeholder image. - -## Using existing icons - -If the icon owner needs to use other icons, perhaps to apply an overlay (although the `CompositeIconId` should handle this), it can use the `IThemedIconManagerPerThemeCache` instance that gets passed in. This interface is a cache of existing icons for the current theme, and can be used to get an icon image, as a WPF `ImageSource` or a `System.Drawing.Bitmap` for a particular DPI. - -```csharp -public interface IThemedIconManagerPerThemeCache -{ - ImageSource GetIconImageSource([NotNull] IconId iconid); - Bitmap GetIconGdipBitmap([NotNull] IconId id, RasterizationResolution resolution); - ImageSource TryGetIconImageSource([NotNull] IconId id); -} -``` - -The images are created on demand, or pulled from the in-memory cache. The `GetIconImageSource` will return the appropriate image, or will return the placeholder. The `TryGetIconImageSource` method will return `null` if it can't find the requested icon. - -## Theming - -It is up to the icon owner to handle theming. Some icons don't partake in theming, for example, `ColorIconId` returns a solid block of colour, which is not appropriate for theming. - -When asked for an icon, one of the items to be passed in is an instance of `IconTheme`. An icon theme is made up of a number of aspects, represented by an array of `IconThemeAspect` instances. There are currently two types of aspect that are recognised - "Generic" and "PsiSymbol". - -The generic aspect represents the colour scheme used by the current theme - colour, gray or dark gray. This can be set explicitly by the user, or set to "automatic", where the aspect is chosen based on the Visual Studio theme. ReSharper analyses the theme to see if it is monochrome, and to see if it is light or dark. For the Blue theme, this gives `GenericThemeAspect.Color`. For the Light theme, `GenericThemeAspect.Gray`, and the Dark theme gives `GenericThemeAspect.DarkGray`. - -The "PsiSymbol" aspect is used to choose which icon set to use for PSI elements such as methods, properties, etc. in code completion lists and file structure windows and so on. Again, this value can be set by the user, but by default is set to automatic. ReSharper will look at the current Visual Studio theme and version, and choose the appropriate symbol set: - -* `PsiSymbolIconThemeAspect.SymbolsIdea` provides symbols based on IntelliJ IDEA -* `PsiSymbolIconThemeAspect.SymbolsVs08` provides symbols used in Visual Studio 2008 -* `PsiSymbolIconThemeAspect.SymbolsVsColor` provides colour symbols as used in Visual Studio 2012 and later -* `PsiSymbolIconThemeAspect.SymbolsVs11Gray` provides monochrome VS2012 symbols for use on a light background -* `PsiSymbolIconThemeAspect.SymbolsVs11GrayDark` provides monochrome VS2012 symbols for use on a dark background - -When the `IIconIdOwner` class needs to return a themed icon, it should look at `IconTheme.Aspects` for aspects it recognises. The array is in priority order, and there may be more than one entry for each aspect kind, to allow for fallbacks. The icon owner should compare the aspect against the known static aspects listed above. When it recognises that aspect, it should provide the appropriate icon. - -How the icon owner chooses to get a theme aspect specific icon is up to the implementation of the icon owner. `CompiledIconId` icons embed several different versions of the icons into an assembly's resources, and the owner simply retrieves the version of the icon that matches the aspect. The `ShellFileIconIdOwner` on the other hand, retrieves a file type icon from the operating system, looks for the `GenericIconThemeAspect.Gray` theme aspect and makes the icon monochrome using `ColorManagement.MakeMonochrome`. - -```csharp -BitmapSource bmp = GetFileIcon(iconid.ExtensionWithDot); -if (theme.Aspects.Contains(GenericIconThemeAspect.Gray)) - return ColorManagement.MakeMonochrome(bmp); -``` - -Both the Light and Dark themes will contain the `Gray` aspect, but the priority ordering is different. This allows for fallback icons. - - > the `IIconIdOwner` class does not need to perform caching. ReSharper will only call the class once per icon per theme. However, the caches are cleared each time the theme changes, so the owner will be called again. diff --git a/topics/Platform/Shell/Icons/IconTypes.md b/topics/Platform/Shell/Icons/IconTypes.md deleted file mode 100644 index 213deb9..0000000 --- a/topics/Platform/Shell/Icons/IconTypes.md +++ /dev/null @@ -1,90 +0,0 @@ -[//]: # (title: Icon Types) - -The most common kind of )`IconId` is `CompiledIconId`. This represents icons that have been compiled into an assembly's resources. ReSharper also supports several other types of icons: - -* **`CompiledIconId`** represents icons that have been compiled into an assembly's resources. -* **`ColorIconId`** represents an icon that is a solid colour. -* **`CompositeIconId`** is an icon that is composed of other `IconId` icons. -* **`EffectOnIconId`** creates an icon based on another `IconId`, applying alpha, made monochrome based on a tint colour, and/or with a blur radius. -* **`ShellFileIconId`** is a file type icon for a given extension. -* **`AnimatedIconId`** and **`RotatedIconId`** represent icons that are animated. - -The icon types don't apply theming, and when creating a new icon based on an existing icon, will create a WPF `ImageSource` that uses the existing icon, meaning WPF will be responsible for scaling the base icon. - -## Color icons - -An icon representing a solid colour can be defined by creating a new instance of `ColorIconId` and passing in a `Color`. The resulting icon will be a solid square of that colour. - -```csharp -var iconId = new ColorIconId(Color.Red); -``` - -## Composite icons - -The `CompositeIconId` will combine other icons into a single image, useful for applying overlays. To create a composite icon, call one of the static `Compose` methods, passing in the `IconId` of the icons to combine. The images are composed in left to right order. That is, the `Compose` method's leftmost argument being applied first, and subsequent arguments are applied on top. - -```csharp -var iconId1 = new ColorIconId(Color.Red); -var iconId2 = ProjectModelThemedIcons.LayerSolutionShared.Id; -var compositeIconId = CompositeIconId.Compose(iconId1, iconId2); -``` - -A more realistic example shows how to create an icon that represents a private method (although this is unlikely to be required in user code, as the PSI can provide this icon automatically for a given declared element): - -```csharp -var iconId1 = PsiSymbolsThemedIcons.Method.Id; -var iconId2 = PsiSymbolsThemedIcons.ModifiersPrivate.Id; -var compositeIconId = CompositeIconId.Compose(iconId1, iconId2); -``` - -## Applying effects to icons - -The `EffectOnIconId` creates a new `IconId` based on an existing icon, but with various effects applied. The new icon can have an alpha opacity value applied, turn the icon monochrome, apply a blur radius, or any combination of the three. Alpha transparency is applied as a double value from 0 to 1, where 1 is no transparency and 0 is fully transparent. Applying the blur radius requires passing in a double value that represents the radius in WPF's Device Independent Units (1/96 of an inch). - -When making the icon monochrome, if the base icon is a WPF vector image, the brushes associated with the vector geometries are replaced with the given colour. When the base icon is a bitmap, the bitmap is rendered and the monochrome colour is applied. - -```csharp -var baseIconId = ProjectModelThemedIcons.LayedSolutionShared.Id; -// Apply a 0.7 opacity, convert to red and apply a radius blur with a radius of 5 -var iconId = new EffectOnIconId(baseIconId, 0.7, Color.Red, 5); -``` - - > `EffectOnIconId` is not intended to be used for theming. Icon types are responsible for their own theming, and should provide icons that are already theme aware. This icon type manipulates an existing icon, which will already be themed if it is appropriate to do so (e.g. `ColorIconId` icons won't be themed, and it's not appropriate for them to be themed). - > - {type="note"} - -## File type icons - -Icons for file types can be retrieved using the `ShellFileIconId` class. These icon IDs ask the operating system for the icon to represent a given file extension (the dot should be included), at a given file size. The returned icon is also converted to monochrome, if the current theme is a monochrome theme (such as Visual Studio's Light or Dark theme. The Blue theme is not, and the icon is not converted if this is the current theme). - -```csharp -var smallIconId = new ShellFileIconId(".cs", ShellFileIconId.IconSize.SmallIcon); -var largeIconId = new ShellFileIconId(".cs", ShellFileIconId.IconSize.LargeIcon); -``` - -Small icons are 16×16 and large icons are 32×32. Since the icons are raster images, they will not scale well, so try to use the appropriate size for the use case. Note that the resulting image does get created for the current DPI, so it will still display correctly in high DPI scenarios. - - > This icon type will convert the icon to monochrome, depending on the current theme. It is up to the icon type to apply appropriate theming. Most other icon types do not need to do this, as they are either manipulating existing icons that are already themed, or because the icon they produce should be displayed as-is. The `CompiledIconId` class will produce theme aware icons, by choosing between multiple sets of icons. - > - {type="note"} - -## Animated icons - -The `AnimatedIconId` and `RotatedIconId` classes are used to get a static image for scenarios where animation is not supported. The `AnimatedIconId` is simply a base class, and `RotatedIconId` is used to identify and provide another `IconId` as a static icon. - -If a `RotatedIconId` is added to a WPF UI using the `ThemedIconViewImage` control (which can be used instead of the WPF `Image` element), then the static image is continuously rotated by a WPF animation, specified in `RotatedIconId.AnimatedRenderTransform`. This is how the animated icons in the unit test runner are rendered. - -For Windows Forms, the individual frames of a rotated animation can be retrieved using `RotatedIconId.GdipBitmapFrames.GetAnimationFrameGdipBitmap`. The `PresentableItemRenderer` class makes use of this to render animation frames for `IPresentableItem` objects that include frames. - -Alternatively, animation can be achieved by creating icons for individual frames and updating an `IProperty` with each frame. Again, this can be used with `ThemedIconViewImage`, which will display each frame as a static image, and update when the icon changes for each frame. This is how the solution wide analysis round icon in the status bar is handled. - -```csharp -public UIElement GetIconView(Lifetime animationLifetime, IProperty animatedIcon) -{ - var image = new ThemedIconViewImage(); - // Bind the property's value to the ThemedIconViewImage's DataContextProperty - // When the icon changes, the DataContextProperty is updated, and the image is redrawn - // The Lifetime dictates when the property binding should be disposed - animatedIcon.FlowInto(animationLifetime, image, DataContextProperty); -} -``` diff --git a/topics/Platform/Shell/Shell_Icons.md b/topics/Platform/Shell/Shell_Icons.md deleted file mode 100644 index e148ca6..0000000 --- a/topics/Platform/Shell/Shell_Icons.md +++ /dev/null @@ -1,11 +0,0 @@ -[//]: # (title: Icons) - -ReSharper supports icons in several places), such as options pages, gutter icons, tied to an action for context menus or toolbars for tool windows. Complicating matters is that ReSharper needs to match the host platform, more specifically, icons need to match the current Visual Studio theme. Also, ReSharper needs to provide support for high DPI scenarios, either by providing multiple bitmap images, automatically scaling, or supporting vector images. - -In order to work with these requirements, ReSharper provides an API for consuming icons, rather than working directly with images. Each icon is identified by an icon id, which is a class that derives from `IconId`. Given an `IconId`, ReSharper can create either a `System.Drawing` (Windows Forms) compatible bitmap, scaled to the current screen DPI, or a WPF `ImageSource`, which can be either a bitmap or a scalable vector image. Furthermore, it can return a "live" version of the icon, which uses `IProperty` to wrap the icon and provide notifications when it's updated, such as when a theme changes. - -ReSharper provides several different types of `IconId`. The most common is `CompiledIconId`, which is a reference to an icon that has been compiled into an assembly's resources. These icons can be created either from PNG files, or scalable WPF `DrawingBrush`. Other types include animated icons, effects applied to icons (such as alpha) and filetype icons. - -Themed icons are supported by the icon ID owners, the components that use the derived `IconId` instances to load the images. When appropriate, they combine the icon ID with the current theme aspect names (e.g. "Dark", "Light", "Color", "SymbolsVs11Color", etc.). - -Internally, icons are represented by WPF `ImageSource` instances, which means transparency is understood and honoured. diff --git a/topics/Platform/Shell/Theming/Theming_Icons.md b/topics/Platform/Shell/Theming/Theming_Icons.md deleted file mode 100644 index 9815c1c..0000000 --- a/topics/Platform/Shell/Theming/Theming_Icons.md +++ /dev/null @@ -1,83 +0,0 @@ -[//]: # (title: Themed Icons) - -ReSharper supports theming icons on two axes )- application colour, and source code symbol style. In other words, icons can be themed either based on the application colour, or on the style for source code symbols. - -The application colour is used to match the theme of the host application, specifically Visual Studio, and is used by icons representing the parts of the application - toolbars, context menus, option pages. The following icon sets are available: - -* **Colour** - used when Visual Studio is in the Blue theme. -* **Gray** - for Visual Studio's Light theme. -* **Dark Gray** - for Visual Studio's Dark theme. - -ReSharper does not hard code Visual Studio's themes, but analyses the theme colours to detect high and low contrast monochrome themes. If the theme does not appear to be monochrome, ReSharper will use the Colour theme. This helps ReSharper better support custom themes. - -The source code symbol style is used by the icons displayed to represent code elements, for example in code completion lists, navigation windows or the file structure window. There are five choices here: - -* **Idea** - the icon set used by IntelliJ IDEA. -* **Gray** - matches the icons used by Visual Studio 2012, in the Light theme. -* **Dark Gray** - matches the icons used by Visual Studio 2012, in the Dark theme. -* **Colour** - matches the icons used by Visual Studio 2012, in a colour theme. -* **Legacy Visual Studio** - matches the icons used by Visual Studio 2008. - -By default, both of these theme aspects are chosen automatically, meaning the application colour will match the environment, and the source code symbols will match the application colour. However, both can be overridden by the user in the options dialog. - -## Identifying the current theme - -The current theme is represented by the `IconTheme` class, and can be retrieved using `IThemedIconManager.CurrentIconTheme` (or `ITheming.CurrentIconTheme`, since `ITheming` inherits from `IThemedIconManger`). The `IconTheme` class is a simple value class that maintains an array of `IconThemeAspect` instances, in priority order. - -A theme aspect represents the two axes described above - application colour and symbol style. The application colour aspect values are represented by static values on the `GenericIconThemeAspect` class: - -```csharp -public static class GenericIconThemeAspect -{ - public static readonly IconThemeAspect Color = new IconThemeAspect(...); - public static readonly IconThemeAspect Gray = new IconThemeAspect(...); - public static readonly IconThemeAspect DarkGray = new IconThemeAspect(...); -} -``` - -The `PsiSymbolIconThemeAspect` class holds the values for the source symbol style: - -```csharp -public static class PsiSymbolIconThemeAspect -{ - public static readonly IconThemeAspect SymbolsIdea = new IconThemeAspect(...); - public static readonly IconThemeAspect SymbolsVs08 = new IconThemeAspect(...); - public static readonly IconThemeAspect SymbolsVs11Color = new IconThemeAspect(...); - public static readonly IconThemeAspect SymbolsVs11Gray = new IconThemeAspect(...); - public static readonly IconThemeAspect SymbolsVs11GrayDark = new IconThemeAspect(...); -} -``` - -When inspecting the `IconTheme.Aspects` array, the values should be compared against the values in `GenericIconThemeAspect` and `PsiSymbolIconThemeAspect`. - -There may be more than one value for each aspect in the `IconTheme.Aspects` array. These are fallback values, and are there for when a particular aspect value is not recognised or supported. The array is stored in priority order, so each value should be inspected in turn and the first recognised icon should be used. - -The symbol style aspects are listed first, so a custom icon set will try to use a specific source symbol style first, then symbol fallbacks, then application colour and colour fallbacks. - -## Using the correct icon theme - -When retrieving an icon for a given `IconId`, the `IThemedIconManager` will automatically use the current theme, by examining the `IconTheme` and its aspects. - -To make sure the icon is updated when the theme changes, either use a "live" image source, or subscribe to the `IThemedIconManager.CurrentIconTheme` observable property, and manually retrieve a new image source from the `IThemedIconManager.Icons` property. - -If using a live image source, e.g. `IThemedIconManager.Icons[myIconId].LiveImageSource` or `IThemedIconManager.Icons[myIconId].LiveGdipBitmapScreenDpi`, then the observable property will notify of changes to the image when the theme changes. - -Alternatively, use the WPF `ThemedIconViewImage` control or the `ThemedIcon` XAML markup extension to automatically update the image source when the theme changes. See [Consuming Icons](ConsumingIcons.md) for more details. - -## Creating theme aware icons - -When creating theme aware icons, each image should be identified by the theme aspect it applies to. The recognised application colour theme aspect names are: - -* **Color** -* **Gray** -* **DarkGray** - -And for source code symbols: - -* **SymbolsIdea** -* **SymbolsVs11Color** -* **SymbolsVs11Gray** -* **SymbolsVs11DarkGray** -* **SymbolsVs08** - -The details of how to specify the aspect name are listed in the [creating compiled icons](CreatingCompiledIcons.md) section. diff --git a/topics/basics/internal_mode.md b/topics/basics/internal_mode.md index a676a72..2aa0acd 100644 --- a/topics/basics/internal_mode.md +++ b/topics/basics/internal_mode.md @@ -29,7 +29,7 @@ Once enabled, ReSharper adds the "Internal" menu to the main "ReSharper" menu. T * **PSI Module Browser** is a tree view of all of the PSI modules in the currently loaded solution. A module is a container for anything that can be referenced, usually source files or referenced assemblies. Each project is a module, as is each referenced assembly. The module browser lists all of the modules, and shows who is referencing them. It also shows the internal modules that ReSharper sets up to add references that are implicit in the project (for example, modules that contain definitions for default global JavaScript objects). * **Code behind** displays a "code behind" view of any secondary PSI trees of the current file. For example, HTML files maintain a hidden, generated, secondary file to represent all of the JavaScript sections in the file. ReSharper can map between the main file and the secondary file, supporting "islands" of one language inside another language. The secondary file can give more context to the islands in the primary file to aid code completion, navigation, etc. * **Settings Store View** allows examining the value of settings, what settings files are currently mounted, and can view the settings schema. -* **Show Themed Icons** provides a tool window to browse and search the icons registered with the [`ThemeIconManager`](Theming_Icons.md), which can be useful to find icons for use in extensions. +* **Show Themed Icons** provides a tool window to browse icons that are shipped with the SDK and to create new compiled icons from SVGs (see [](Platform__Icons.md)) * **Show Change Manager Graph in yEd** will create a graph file to be opened in the [yEd graphing application](http://www.yworks.com/en/products/yfiles/yed/) showing change providers, and how they are registered. Other items are available, these are just some of the more interesting ones for extension developers.