Skip to content

Commit 52a184e

Browse files
TomSmartBishopTomSmartBishop
authored
Update Readme.md
1 parent 32b0d07 commit 52a184e

File tree

1 file changed

+103
-1
lines changed

1 file changed

+103
-1
lines changed

‎Readme.md‎

Lines changed: 103 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,103 @@
1-
# ImageComments (a Visual Studio Extension)This fork is an updated version with all sound patches from the different forks out there. all sound patches from the different forks out there.## OverviewThis is an extension for the Visual Studio code editor that allows images to be displayed amongst code, allowing for visually rich comments. For example...![](http://lukesdm.github.com/image-comments/media/example-1.png)## Usage Info### PreambleDisclaimer: This project is a WIP and it's pretty rough around the edges. Please report issues on the GitHub repo.Supported Visual Studio Verions 2010~2015 (2017 warns about missing support, but works)### Download/Installation[Latest 1.1.4.4](https://github.com/TomSmartBishop/image-comments/raw/master/Output/ImageComments.vsix)To install double-click/activate the VSIX file.### How to useImage-comments are declared with:`/// <image url="X:\Path\To\Image.ext" scale="1.5" />` or `/// <img src="X:\Path\To\Image.ext" scale="1.5" />`The optional `scale` attribute multiplies the source width and height (ranges from 0.01 to 100). Since 1.1.4.4 scaled images are anti aliased.The optional `opacity` attribute is available since 1.1.4.4 (from 0.0 to 1.0): `/// <image url="..\Image.ext" opacity="0.6" />``// <image url="X:\Path\To\TransparentImage.png" bgcolor="ffffff" />`You can also specify the `bgcolor` attribute to set a background color for pictures with transparent areas, the color is specified as hex number: RRGGBB or RRGGBBAA, optionally you can use a short hand notation RGB.You can use the VS environment variables $(ProjectDir), $(SolutionDir), and $(ItemDir) in URLs, e.g.:`# <image url="$(SolutionDir)\CommonImages\Fourier.jpg" />` From 1.1.4.3 on you can also use relative paths (relative to the source file).Images from URL will be downloaded and not updated as long as the file exists in the user temp directory.Please note, if you use docfx at the same time, these environment variables must not be used, because docfx expects the images in a directory, e.g. "./images".Images are displayed using the [WPF Image control](http://msdn.microsoft.com/en-us/library/ms610982) with a [BitmapFrame](http://msdn.microsoft.com/en-us/library/ms619213) source, and accepted image and URL formats are tied to those, e.g. BMP, PNG, JPG all work as image formats, and C:\Path\To\Image.png, http://www.server.com/image.png and \\\server\folder\image.png all work as URLs.If there's a problem trying to load the image or parse the tag, the tag will be squiggly-underlined and hovering over this will show the error, e.g![](http://lukesdm.github.com/image-comments/media/error-example-1.png)The languages currently supported are Python, C#, F# (fixme), C, C++ and VB.Image-comments don't really have anything to do with XML comments, but the format is convenient and it should be pretty straight-forward to transform them for Sandcastle documentation creation.The extension adds a command in the Tools menu to toggle image-comment display on or off.### UninstallationIn VS, open the Extension Manager, select ImageComments, then click uninstall. A restart of VS is required.### Some known issues* After adding an image-comment using a local image, you can't edit the image until VS is closed.* The caret/selection highlight height on image-comment lines grows as high the image.* You need to scroll/'bump' the editor window to see the effect of the on/off toggle command.## Development InfoRequires: Visual Studio 2015 SDK### Build instructionsProviding the VS SDK is installed, you should be able to build by opening the solution and hitting F6. Debugging has to be configured manually - On the Project Properties->Debug tab, choose 'Start External Program' and command line e.g. (if using default install location) 'C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\devenv.exe' with arguments '/rootsuffix Exp'. The 'Release' build configuration copies the .vsix package into the Solution's .\Output directory.### Program structureIt's a very small project and may be fairly self explanatory if you are familiar with Visual Studio editor extensions.There are two components to the extension:* ImageCommentsEditorComponent. Contains 97% of the functionality.* ImageCommentsPackage. Adds a command to enable/disable functionality; VSIX definition.For testing information, see .\Testing\Testing.html### Some known implementation issuesThe code is a bit rough - it may not need a rewrite from scratch, but there's a bunch of stuff to be done* Images downloaded from an URL might not show up right away* Error/exception handling should be improved* Program/project structure could be improved* No automated tests and manual testing has been limited.* There are some fairly obvious potential optimisations, but so far performance impact on plain Visual Studio seems minimal (in a release build on a 1.4GHz Core 2 Duo laptop with 1GB RAM). It would probably just add unneccessary complexity, but further testing might show otherwise.* ...## LicenseEclipse Public License v1.0. See [license text](http://github.com/lukesdm/image-comments/raw/master/License.txt) for details.## AuthorThe original plugin was made by Luke McQuade, this fork is maintained by Thomas Pollak. Further contributors: Lionsoft, Oleg Kosmakov, Morten Engelhardt Olsen, Wolfgang Kleinschmit, Sören Nils Kuklau, Tim Long
1+
# ImageComments (a Visual Studio Extension)
2+
3+
This fork is an updated version with all sound patches from the different forks out there. all sound patches from the different forks out there.
4+
5+
## Overview
6+
This is an extension for the Visual Studio code editor that allows images to be displayed amongst code, allowing for visually rich comments. For example...
7+
8+
![](http://lukesdm.github.com/image-comments/media/example-1.png)
9+
10+
## Usage Info
11+
12+
### Preamble
13+
Disclaimer: This project is a WIP and it's pretty rough around the edges. Please report issues on the GitHub repo.
14+
15+
Supported Visual Studio Verions 2010~2015 (2017 warns about missing support, but works)
16+
17+
### Download/Installation
18+
[Latest 1.1.4.4](https://github.com/TomSmartBishop/image-comments/raw/master/Output/ImageComments.vsix)
19+
20+
To install double-click/activate the VSIX file.
21+
22+
### How to use
23+
Image-comments are declared with:
24+
25+
`/// <image url="X:\Path\To\Image.ext" scale="1.5" />` or `/// <img src="X:\Path\To\Image.ext" scale="1.5" />`
26+
27+
The optional `scale` attribute multiplies the source width and height (ranges from 0.01 to 100). Since 1.1.4.4 scaled images are anti aliased.
28+
29+
The optional `opacity` attribute is available since 1.1.4.4 (from 0.0 to 1.0):
30+
`/// <image url="..\Image.ext" opacity="0.6" />`
31+
32+
`// <image url="X:\Path\To\TransparentImage.png" bgcolor="ffffff" />`
33+
You can also specify the `bgcolor` attribute to set a background color for pictures with transparent areas, the color is specified as hex number: RRGGBB or RRGGBBAA, optionally you can use a short hand notation RGB.
34+
35+
You can use the VS environment variables $(ProjectDir), $(SolutionDir), and $(ItemDir) in URLs, e.g.:
36+
37+
`# <image url="$(SolutionDir)\CommonImages\Fourier.jpg" />`
38+
39+
From 1.1.4.3 on you can also use relative paths (relative to the source file).
40+
41+
Images from URL will be downloaded and not updated as long as the file exists in the user temp directory.
42+
43+
Please note, if you use docfx at the same time, these environment variables must not be used, because docfx expects the images in a directory, e.g. "./images".
44+
45+
46+
Images are displayed using the [WPF Image control](http://msdn.microsoft.com/en-us/library/ms610982) with a [BitmapFrame](http://msdn.microsoft.com/en-us/library/ms619213) source, and accepted image and URL formats are tied to those, e.g. BMP, PNG, JPG all work as image formats, and C:\Path\To\Image.png, http://www.server.com/image.png and \\\server\folder\image.png all work as URLs.
47+
48+
49+
If there's a problem trying to load the image or parse the tag, the tag will be squiggly-underlined and hovering over this will show the error, e.g
50+
51+
52+
![](http://lukesdm.github.com/image-comments/media/error-example-1.png)
53+
54+
55+
The languages currently supported are Python, C#, F# (fixme), C, C++ and VB.
56+
57+
58+
Image-comments don't really have anything to do with XML comments, but the format is convenient and it should be pretty straight-forward to transform them for Sandcastle documentation creation.
59+
60+
61+
The extension adds a command in the Tools menu to toggle image-comment display on or off.
62+
63+
64+
### Uninstallation
65+
In VS, open the Extension Manager, select ImageComments, then click uninstall. A restart of VS is required.
66+
67+
### Some known issues
68+
* After adding an image-comment using a local image, you can't edit the image until VS is closed.
69+
* The caret/selection highlight height on image-comment lines grows as high the image.
70+
* You need to scroll/'bump' the editor window to see the effect of the on/off toggle command.
71+
72+
## Development Info
73+
Requires: Visual Studio 2015 SDK
74+
75+
### Build instructions
76+
Providing the VS SDK is installed, you should be able to build by opening the solution and hitting F6. Debugging has to be configured manually - On the Project Properties->Debug tab, choose 'Start External Program' and command line e.g. (if using default install location) 'C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\devenv.exe' with arguments '/rootsuffix Exp'. The 'Release' build configuration copies the .vsix package into the Solution's .\Output directory.
77+
78+
### Program structure
79+
It's a very small project and may be fairly self explanatory if you are familiar with Visual Studio editor extensions.
80+
There are two components to the extension:
81+
82+
* ImageCommentsEditorComponent. Contains 97% of the functionality.
83+
* ImageCommentsPackage. Adds a command to enable/disable functionality; VSIX definition.
84+
85+
For testing information, see .\Testing\Testing.html
86+
### Some known implementation issues
87+
The code is a bit rough - it may not need a rewrite from scratch, but there's a bunch of stuff to be done
88+
89+
* Images downloaded from an URL might not show up right away
90+
* Error/exception handling should be improved
91+
* Program/project structure could be improved
92+
* No automated tests and manual testing has been limited.
93+
* There are some fairly obvious potential optimisations, but so far performance impact on plain Visual Studio seems minimal (in a release build on a 1.4GHz Core 2 Duo laptop with 1GB RAM). It would probably just add unneccessary complexity, but further testing might show otherwise.
94+
* ...
95+
96+
## License
97+
Eclipse Public License v1.0. See [license text](http://github.com/lukesdm/image-comments/raw/master/License.txt) for details.
98+
99+
## Author
100+
The original plugin was made by Luke McQuade, this fork is maintained by Thomas Pollak. Further contributors: Lionsoft, Oleg Kosmakov, Morten Engelhardt Olsen, Wolfgang Kleinschmit, Sören Nils Kuklau, Tim Long
101+
102+
103+

0 commit comments

Comments
 (0)