Specify What to Edit for User

Question

Ephraim Bryski 2019-7-10

0
链接

此问题的直接链接

https://ww2.mathworks.cn/matlabcentral/answers/471054-specify-what-to-edit-for-user

编辑： per isakson 2019-7-30

I'm writing code which should allow the user to edit certain sections, and I want to make it clear to the user where they should edit (it doesn't have to prevent them from editing other stuff). The user would select what they want to modify in the code (through a GUI) and it would take them to the correct section of the code. I thought of a number of options (unfolding only that section, disabling editing other code, moving to the correct line) but I couldn't find a command to do any of these things. (Having it display something in line through live editor won't work because it's a class). Does anyone know how you might implement this?

26 个评论
显示 24更早的评论隐藏 24更早的评论

Ephraim Bryski 2019-7-10

编辑：Ephraim Bryski 2019-7-12

The user would do fairly basic things (also for now I'm the user). For example there are properties for physical constants but the user might want to add some more properties. The idea is the user is writing their own code to create a class. I just have it set up to make it easier and already have some properties included.

The main purpose of the GUI is also not to help them add properties. It's mainly to provide an interface for them to call functions which use those properties. I could instead require the user to just manually go the right section and write their code and it would work essentially the same way.

EDIT: I finished writing a very rudimentary code which allows users to create their own constants (properties) and parameters (methods). Right now there's a single class which has everything, but if I were to make it more general, I think it would make sense to make subclasses. There would be a main class with fundamental things (like physical constants). Then there would be subclasses (and then maybe subclasses with in subclasses) which are more specific. The user would be able to create a subclass with constants and parameters specific for their project. Because I'm working on a single project, that's not very useful for me to implement right now though.

Ephraim Bryski 2019-7-12

编辑：Ephraim Bryski 2019-7-12

Thank you very much for the advice! Yes, I was considering removing the GUI altogether, but I thought it would too hard for the user to access things without it. For example, now there's a drop down which lists all the functions (associated with types of graphs) which the user could select. It searches the directory where plot functions are stored and adds the name of all the functions to the list. Then when you create a new function you save it in the directory so it automatically adds that function. I don't know how I would implement something like that without a GUI (of course they could just call the function but then they would have to get the name just right). I could even allow them to start typing the name of the function and it would find the ones which start with that name (I have NOT implemented that yet, but I don't think it would be very hard).

The GUI is designed to do as little as possible. The only code within the GUI is to disable certain buttons (for example if I want to save figures I would want to disable the field which selects which trial to iterate through but iterate through all of them), code to call refresh (which refreshes the drop down), a call (I actually use run) to the selected function, a command to open the class, and a command to open the template function

As for API, I don't know what to say about that because I honestly had to search it up to find out what it means. I'm essentially learning all this stuff as I make the program. I've only been working on it for two weeks and it's basically been a constants process of learning about coding, figuring out what would make sense to implement, and then implementing it. For example, a few days ago I only had a very crude idea of what classes even were.

Ephraim Bryski 2019-7-12

编辑：Ephraim Bryski 2019-7-12

I think I see what you mean. The user could instead just search for the function (maybe just by clicking the open button) find the function and then run it. (Edit: I realize now this is NOT what you mean). To be fair though, the refresh function is only 10 or so lines.

Also there's no code to add the function to the search path. The user just selects the right folder to save it in it. This would enable them to make different folders (by this I mean actually making folders as you normally would) where different types of functions to create plots is stored.

As for the function hint, I was not thinking of implementing it any time soon, and after discussing it with you, I guess it might be better not to.

Ok for docoment I imagine you mean something detects what the search path is (for example) and then can return an error based on that. I'm still not sure how I would implement that though.

As for making a function handle an input, I don't quite get what you mean. So there are two functions you're referring to, one with a handle as an input, and one being the function whose handle is being inputted. What would these two functions be? (When searching up the documentation for inputting function handles it only lists built in functions and antonymous functions so I'm also not sure how I would use it). https://www.mathworks.com/help/matlab/matlab_prog/pass-a-function-to-another-function.html

Guillaume 2019-7-12

Would this still be an API?

The API is basically a contract between your code and the user. You tell the user: to achieve this task, you use this function/class/whatever with these inputs, and you get that in return. As long as they follow the contract, everything works (baring bugs), if they don't stick to their side of the contract (supplying required inputs that follow the contract), then they're outside of the API and shouldn't have any expectation that anything work (it may or may not). The API can be made of many functions/classes or just one.

You don't have to call it an API. What is important as Stephen and I said, is that you document your interface. See the matlab documentation for an example of fairly good documentation. An important part of a documentation is explaining what your function expects as input and how that affects the output. Writing good documentation requires some effort. However, undocumented code is useless to anybody but the author (and even then, 6 months later the author may have forgotten).

Note that documenting your API includes specifying what class of inputs are expected (numeric, string, char array, cell array, logical, etc.), what shape is allowed (scalar, row vector, column vector, matrix, ND array, etc.). Same for outputs. Using validateattributes at the beginning of a function is a good way to check that the user is conforming to your contract.

Guillaume 2019-7-12

在 MATLAB Online 中打开

At the most basic, documentation can be just comments at the start of the function or within the class. Later on, you can do something more fancy (follow the links at the bottom of that documentation), or write your documentation as a Word/PDF/whatever takes your fancy.

Here is an example of class documentation that I'd consider good. You can see that the DrawText method relies on an inputParser to check that the user conformed to the documented API.

classdef (Sealed) ImageCanvas < handle
%ImageCanvas: Allows drawing text and shapes onto images
%All the drawing is delegate to .Net, so this only works on Windows.
%
%In order to draw on an image, it must first be converted into a canvas.
%All drawing is done onto the canvas, and when needed, the canvas can then be converted back into an image
%Note that canvas are always 8-bit true colour images. Original images in other format will always be converted to that format
%A canvas is created simply by passing an input image to the ImageCanvas constructor. 
%
%   canvas = ImageCanvas(someimage);
%
%Member methods of ImageCanvas can then be called to draw on the canvas. 
%All drawing methods will require at least one of the following object as well(unless defaults are used):
%  Font: for text drawing methods, specify which font and font style to use.
%  Brush: for any drawing with filled shapes (including text), specify colour and texture of the filled shape. 
%         Brush has several derived implementations: 
%               SolidBrush: A basic brush that fills the shape with a solid colour.
%               HatchBrush: A brush that fills the shape with a hatch pattern. 
%  Pen: for drawing anything with lines, specify the colour, thickness, endpoints, etc. of the lines
%
%To retrieve an image, after having drawn on the canvas, call GetImage:
%
%   newimage = canvas.GetImage;
%
%The width and height of the canvas can be queried at any time, it's the same width and height as the input image:
%
%  width = canvas.Width;
%  height = canvas.Height;
%
%The following methods are currently implemented:
%  DrawText(Text, Location, name, value...): Draw text at specific location. 
%           Text                        The text to draw on the image. char row vector or scalar string.
%           Location                    Location in pixels of the upper left corner of the text box as a 2 element vector [x, y] of any numeric type. Coordinates are .Net based. Upper left corner of the image is [0,0]
%       The following name/value parameters are available
%           'Font', font                Use the given font to draw the text, can be a Font object or a .Net System.Drawing.Font object. If unspecified, matlab's default font is used.
%           'Brush', brush              Use the given brush to draw the text, can be any Brush derived object or a .Net System.Drawing.Brush object. If unspecified, a solid black brush is used.
%           'BoxSize', [width, height]  Clips text to box size in pixels. If not specified the text is clipped to the image.
%
    [...] code removed
        
    properties (Dependent)
        Width;      %Width of the canvas. Same as the original image.
        Height;     %Height of the canvas. Same as the original image.
    end
    methods
        function this = ImageCanvas(image)
            %Construct an ImageCanvas from an image
            %the image is stored as a truecolour 8-bit image
            %   canvas = ImageCanvas(image)
            %       image: 2D or 3D numeric matrix. if double, intensities must be in the range 0-1. Indexed images are not supported 
            [...] code removed
        end
                
        function DrawText(this, varargin)
            %Draw text onto the canvas
            %  canvas.DrawText(Text, Location, name, value...)
            %           Text                        The text to draw on the image. char row vector or scalar string.
            %           Location                    Location in pixels of the upper left corner of the text box as a 2 element vector [x, y] of any numeric type. Coordinates are .Net based. Upper left corner of the image is [0,0]
            %       The following name/value parameters are available
            %           'Font', font                Use the given font to draw the text, can be a Font object or a .Net System.Drawing.Font object. If unspecified, matlab's default font is used.
            %           'Brush', brush              Use the given brush to draw the text, can be any Brush derived object or a .Net System.Drawing.Brush object. If unspecified, a solid black brush is used.
            %           'BoxSize', [width, height]  Clips text to box size in pixels. If not specified the text is clipped to the image. 
            %
            parser = inputParser;
            parser.FunctionName = 'ImageCanvas.DrawText';
            parser.addRequired('Text', @(text) validateattributes(text, {'char', 'string'}, {'scalartext'}));
            parser.addRequired('Location', @(location) validateattributes(location, {'numeric'}, {'numel', 2, 'nonnegative', 'finite'}));
            parser.addOptional('Font', Font, @(font) validateattributes(font, {'Font', 'System.Drawing.Font'}, {'scalar'}));
            parser.addOptional('Brush', SolidBrush, @(brush) validateattributes(brush, {'Brush', 'System.Drawing.Brush'}, {'scalar'}));
            parser.addOptional('BoxSize', [], @(boxsize) validateattributes(boxsize, {'numeric'}, {'numel', 2, 'nonnegative', 'finite', 'real'}));
            parser.parse(varargin{:});
            [...] code removed

Ephraim Bryski 2019-7-12

编辑：Ephraim Bryski 2019-7-12

Yes, that is exactly what I meant. I'm still very new to this, so my terminology is pretty lousy. When I say variable name I meant any thing where you would say

(my idea of variable name)=(something)

I realize that's not correct now though.

This is a very specific question, but important for me and may help me improve the overall code. I'm supposed to make an animation, but when I run it it's incredibly slow now that I've implemented it (like it would take hours to finish slow). I made inputs to the function where all the inputs are handles (to clarify:

if I were to type the input into the command window it would give:

(my_input)=(something (cell array, matrix whatever))

)

so inputting it should NOT

require it to access the class. I'm not sure what is causing it to be slow (but I'm supposed to update the animation -- change the annotation a bit -- and show it to the mentor today) so I really need to figure out what could be wrong. Saying my program causes it to be really slow wouldn't be that good.

Ephraim Bryski 2019-7-12

编辑：Ephraim Bryski 2019-7-12

So I think the idea is I would create the API and the user would basically have to learn how to use it. There would documentation they could get with help (some name of my function) and it would throw things like warnings or errors if they're not using it properly (the API would somehow have to know what the users trying to do and decide if it's ok).

I think I'm going to save some new code which doesn't have any of the specifics for my project (so you don't have to look through hundreds of irrelevant lines of code) add some very basic documentation (at least some stuff you could access with help) and upload it to an opensource forum. Then I'll add the link here and anyone who wants to can edit it. I think I'll keep the GUI but the first step might be getting rid of it. Hopefully I'll have it uploaded by Monday or so.

I do want to make this specific for water related stuff (things like experiments where waves impact objects) so certain specific code (like calculating uplift from pressure gauges) would also be uploaded.

Ephraim Bryski 2019-7-13

I thought about all this and I described how the api should work here. I still have to learn a bit more I think before I start coding (things like handle functions, handle functions as inputs, assert). I also don't know how good my basic idea so far is.

请先登录，再进行评论。

请先登录，再回答此问题。

Answer 1

Image Analyst 2019-7-12

0
链接

此回答的直接链接

https://ww2.mathworks.cn/matlabcentral/answers/471054-specify-what-to-edit-for-user#answer_382996

I'd just use app designer or guide and make a gui with either 3 radio buttons or a drop down list (popup) with three selections. Then in the main part of your code, you can check the state of the GUI controls to see which of your available options they selected.

4 个评论
显示 2更早的评论隐藏 2更早的评论

Image Analyst 2019-7-13

I still think you're making it way more complicated than necessary by doing such low level API coding manually.

Ephraim Bryski 2019-7-13

If you're referring to the GUI, I decided the first thing I'll do is get rid of it.

请先登录，再进行评论。

Specify What to Edit for User

26 个评论
显示 24更早的评论隐藏 24更早的评论

回答（1 个）

4 个评论
显示 2更早的评论隐藏 2更早的评论

另请参阅

类别

标签

产品

版本

Community Treasure Hunt

Specify What to Edit for User

26 个评论 显示 24更早的评论隐藏 24更早的评论

回答（1 个）

4 个评论 显示 2更早的评论隐藏 2更早的评论

另请参阅

类别

标签

产品

版本

Community Treasure Hunt

26 个评论
显示 24更早的评论隐藏 24更早的评论

4 个评论
显示 2更早的评论隐藏 2更早的评论